[01/58] [abbrv] isis git commit: ISIS-1521: fixes xref links between guides

[da...@apache.org]

Repository: isis
Updated Branches:
  refs/heads/wip [created] e47aa0b0a


http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_file-based.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_file-based.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_file-based.adoc
index 6a2a0b4..513542a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_file-based.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_file-based.adoc
@@ -11,15 +11,15 @@ Metadata providing UI hints can be specified either xref:ugvw.adoc#_ugvw_layout_
 Using a file-based layout has the huge benefit that the layout can be updated without requiring a recompile of the code and redeploy of the app.
 Many developers also find it easier to rationalize about layout when all the hints are collated together in a single place (rather than scattered across the class members as annotations).
 
-Another benefit of file-based layout is that UI hints can be provided for xref:ugfun.adoc#_ugfun_how-tos_contributed-members[contributed associations and actions] that are synthesised at runtime.
+Another benefit of file-based layout is that UI hints can be provided for xref:../ugfun/ugfun.adoc#_ugfun_how-tos_contributed-members[contributed associations and actions] that are synthesised at runtime.
 
-It is also possible to download an initial `.layout.xml` - capturing any existing layout metadata - using the xref:rgsvc.adoc#_rgsvc_api_LayoutService[`LayoutService`] (exposed on the prototyping menu) or using a xref:rgcms.adoc#_rgcms_classes_mixins_Object[mixin action] contributed to every domain object.
+It is also possible to download an initial `.layout.xml` - capturing any existing layout metadata - using the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_LayoutService[`LayoutService`] (exposed on the prototyping menu) or using a xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins_Object[mixin action] contributed to every domain object.
 
 The main downsides of using file-based layouts are a lack of typesafety (a typo will result in the metadata not being picked up for the element) and syntactic fragility (an invalid XML document will result in no metadata for the entire class).
 
 Also, file-based layouts have no notion of inheritance, whereas the dewey-decimal format `@MemberOrder` annotation allows the metadata of the subclass its superclasses to fit together relatively seamlessly.
 
-The `Xxx.layout.xml` file is just the serialized form of a xref:rgcms.adoc#_rgcms_classes_layout[`Grid`] layout class defined within Apache Isis' applib.  These are JAXB-annotated classes with corresponding XSD schemas; the upshot of that
+The `Xxx.layout.xml` file is just the serialized form of a xref:../rgcms/rgcms.adoc#_rgcms_classes_layout[`Grid`] layout class defined within Apache Isis' applib.  These are JAXB-annotated classes with corresponding XSD schemas; the upshot of that
 is that IDEs such as IntelliJ and Eclipse can provide "intellisense", making iteasy to author such layout files.
 
 
@@ -28,7 +28,7 @@ is that IDEs such as IntelliJ and Eclipse can provide "intellisense", making ite
 It is also possible to describe layouts using a `.layout.json` file.
 However, `.layout.json` support is deprecated; the ``.layout.xml`` file also enables much more sophisticated layouts than those afforded by ``.layout.json``.
 
-If you have an application with older `.layout.json` files, then it is possible to download initial `.layout.xml` files using the xref:rgsvc.adoc#_rgsvc_api_LayoutService[`LayoutService`] (exposed as an action on the prototyping menu).
+If you have an application with older `.layout.json` files, then it is possible to download initial `.layout.xml` files using the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_LayoutService[`LayoutService`] (exposed as an action on the prototyping menu).
 The `.layout.json` file will be ignored once a `.layout.xml` file is present.
 ====
 
@@ -43,7 +43,7 @@ The rows and columns are closely modelled on link:getbootstrap.com[Bootstrap 3]
 
 * those that defines common components, of: fieldsets (previously called member groups or property groups), properties, collections, actions and also the title/icon of the domain object itself.
 
-More information about these classes can be found in xref:rgcms.adoc#_rgcms_classes_layout[the reference guide].  More information on Bootstrap 3's grid system can be found link:http://getbootstrap.com/css/#grid[here].
+More information about these classes can be found in xref:../rgcms/rgcms.adoc#_rgcms_classes_layout[the reference guide].  More information on Bootstrap 3's grid system can be found link:http://getbootstrap.com/css/#grid[here].
 
 
 == Screencast
@@ -117,7 +117,7 @@ This corresponds to the following XML:
 ----
 
 
-You will notice that one of the ``col``umns has an ``unreferencedActions`` attribute, while one of the ``tabGroup``s has a similar ``unreferencedCollections`` attribute.  This topic is discussed in more detail xref:ugfun.adoc#__ugvw_layout_file-based_unreferenced[below].
+You will notice that one of the ``col``umns has an ``unreferencedActions`` attribute, while one of the ``tabGroup``s has a similar ``unreferencedCollections`` attribute.  This topic is discussed in more detail xref:../ugfun/ugfun.adoc#__ugvw_layout_file-based_unreferenced[below].
 
 
 
@@ -160,7 +160,7 @@ In the first column there is a single fieldset.  Notice how actions - such as `d
 
 Thereafter the fieldset lists the properties in order.  Actions can be associated with properties too; here they are rendered underneath or to the right of the field.
 
-Note also the `unreferencedProperties` attribute for the fieldset; this topic is discussed in more detail xref:ugfun.adoc#__ugvw_layout_file-based_unreferenced[below].
+Note also the `unreferencedProperties` attribute for the fieldset; this topic is discussed in more detail xref:../ugfun/ugfun.adoc#__ugvw_layout_file-based_unreferenced[below].
 
 
 === Collections
@@ -321,7 +321,7 @@ from the top of the page slightly, using the following CSS:
 
 == Migrating from earlier versions
 
-As noted earlier on, it is possible to download layout XML files using the xref:rgsvc.adoc#_rgsvc_api_LayoutService[`LayoutService`] (exposed on the prototyping menu); this will download a ZIP file of layout XML files for all domain entities and view models.  Alternatively the layout XML for a single domain object can be downloaded using the xref:rgcms.adoc#_rgcms_classes_mixins_Object[mixin action] (contributed to every domain object).
+As noted earlier on, it is possible to download layout XML files using the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_LayoutService[`LayoutService`] (exposed on the prototyping menu); this will download a ZIP file of layout XML files for all domain entities and view models.  Alternatively the layout XML for a single domain object can be downloaded using the xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins_Object[mixin action] (contributed to every domain object).
 
 There are four "styles":
 
@@ -341,9 +341,9 @@ below summarises the choices:
 |===
 
 | Style
-|xref:rgant.adoc#_rgant-MemberGroupLayout[`@MemberGroupLayout`]
-| xref:rgant.adoc#_rgant-MemberOrder[`@MemberOrder`]
-| xref:rgant.adoc#_rgant-ActionLayout[`@ActionLayout`], xref:rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`], xref:rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`]
+|xref:../rgant/rgant.adoc#_rgant-MemberGroupLayout[`@MemberGroupLayout`]
+| xref:../rgant/rgant.adoc#_rgant-MemberOrder[`@MemberOrder`]
+| xref:../rgant/rgant.adoc#_rgant-ActionLayout[`@ActionLayout`], xref:../rgant/rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`], xref:../rgant/rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`]
 
 
 |`COMPLETE`
@@ -381,11 +381,11 @@ Download either for a single domain object, or download all domain objects (enti
 
 For more information about layouts, see:
 
-* xref:rgsvc.adoc#_rgsvc_api_LayoutService[`LayoutService`] (whose functionality is exposed on the prototyping menu as an action) and lso the a xref:rgcms .adoc#_rgcms_classes_mixins_Object[mixin action]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_LayoutService[`LayoutService`] (whose functionality is exposed on the prototyping menu as an action) and lso the a xref:rgcms .adoc#_rgcms_classes_mixins_Object[mixin action]
 
-* xref:rgsvc.adoc#_rgsvc_spi_GridService[`GridService`] and its supporting services, xref:rgsvc.adoc#_rgsvc_spi_GridLoaderService[`GridLoaderService`] and xref:rgsvc.adoc#_rgsvc_spi_GridSystemService[`GridSystemService`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_GridService[`GridService`] and its supporting services, xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_GridLoaderService[`GridLoaderService`] and xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_GridSystemService[`GridSystemService`]
 
-* xref:rgcms.adoc#_rgcms_classes_layout[grid layout classes], defined in the Apache Isis applib
+* xref:../rgcms/rgcms.adoc#_rgcms_classes_layout[grid layout classes], defined in the Apache Isis applib
 
 
 
@@ -414,4 +414,4 @@ Any `.layout.xml` files must be compiled and available in the classpath.  Ensure
 </resources>
 ----
 
-If using an Apache Isis xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype], then the POM is already correctly configured.
+If using an Apache Isis xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype], then the POM is already correctly configured.

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_table-columns.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_table-columns.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_table-columns.adoc
index 229217d..36fe1bd 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_table-columns.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_table-columns.adoc
@@ -7,7 +7,7 @@
 
 
 
-The optional xref:rgsvc.adoc#_rgsvc_spi_TableColumnOrderService[`TableColumnOrderService`] SPI service can be used to reorder columns in a table, either for a parented collection (owned by parent domain object) or a standalone collection (returned from an action invocation).
+The optional xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_TableColumnOrderService[`TableColumnOrderService`] SPI service can be used to reorder columns in a table, either for a parented collection (owned by parent domain object) or a standalone collection (returned from an action invocation).
 
 For example, suppose there is a `Customer` and an `Order`:
 

[02/58] [abbrv] isis git commit: ISIS-1521: fixes xref links between guides

[da...@apache.org]

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_drop-downs-and-defaults.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_drop-downs-and-defaults.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_drop-downs-and-defaults.adoc
index d23c350..9db7ccc 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_drop-downs-and-defaults.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_drop-downs-and-defaults.adoc
@@ -13,15 +13,15 @@ NOTE: FIXME
 
 ### Choices for Property
 
-NOTE: FIXME - xref:rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`]
+NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`]
 
 ### Auto-complete for property
 
-NOTE: FIXME - xref:rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`]
+NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`]
 
 ### Default for property
 
-NOTE: FIXME -  xref:rgcms.adoc#_rgcms_methods_prefixes_default[`default...()`]
+NOTE: FIXME -  xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_default[`default...()`]
 
 
 
@@ -32,19 +32,19 @@ NOTE: FIXME
 
 ### Choices for action parameter
 
-NOTE: FIXME - xref:rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`]
+NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`]
 
 ### Dependent choices for action params
 
-NOTE: FIXME - xref:rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`]
+NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`]
 
 ### Auto-complete for action param
 
-NOTE: FIXME - xref:rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`]
+NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`]
 
 ### Default for action param
 
-NOTE: FIXME -  xref:rgcms.adoc#_rgcms_methods_prefixes_default[`default...()`]
+NOTE: FIXME -  xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_default[`default...()`]
 
 
 
@@ -57,9 +57,9 @@ NOTE: FIXME
 
 ### Drop-down for limited number of instances
 
-NOTE: FIXME - xref:rgant.adoc#_rgant-DomainObject_bounded[`@DomainObject#bounded()`]
+NOTE: FIXME - xref:../rgant/rgant.adoc#_rgant-DomainObject_bounded[`@DomainObject#bounded()`]
 
 
 ### Auto-complete (repository-based)
 
-xref:rgant.adoc#_rgant-DomainObject_autoCompleteRepository[`@DomainObject#autoCompleteRepository()`]
+xref:../rgant/rgant.adoc#_rgant-DomainObject_autoCompleteRepository[`@DomainObject#autoCompleteRepository()`]

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_simulating-collections-of-values.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_simulating-collections-of-values.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_simulating-collections-of-values.adoc
index 694baae..4402b7c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_simulating-collections-of-values.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_simulating-collections-of-values.adoc
@@ -19,5 +19,5 @@ NOTE: FIXME
 
 == Persistence Concerns
 
-NOTE: FIXME -  easiest to simply store using DataNucleus' support for collections, marked as xref:rgant.adoc#_rgant-Programmatic[`@Programmatic`] so that it is ignored by Apache Isis.  Alternatively can store as json/xml in a varchar(4000) or clob and manually unpack.
+NOTE: FIXME -  easiest to simply store using DataNucleus' support for collections, marked as xref:../rgant/rgant.adoc#_rgant-Programmatic[`@Programmatic`] so that it is ignored by Apache Isis.  Alternatively can store as json/xml in a varchar(4000) or clob and manually unpack.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_action-icons-and-css.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_action-icons-and-css.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_action-icons-and-css.adoc
index 36f6924..3a62241 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_action-icons-and-css.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_action-icons-and-css.adoc
@@ -11,7 +11,7 @@ These UI hint can be applied either to individual actions, or can be applied en-
 
 == Per action
 
-NOTE: FIXME - xref:rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout#cssClass()`] and xref:rgant.adoc#_rgant-ActionLayout_cssClassFa[`@ActionLayout#cssClassFa()`]
+NOTE: FIXME - xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout#cssClass()`] and xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClassFa[`@ActionLayout#cssClassFa()`]
 
 
 Alternatively, you can specify these hints dynamically in the xref:ugvw.adoc#_ugvw_layout[`Xxx.layout.json`] for the entity.
@@ -19,9 +19,9 @@ Alternatively, you can specify these hints dynamically in the xref:ugvw.adoc#_ug
 
 == Per pattern matching
 
-Rather than annotating every action with xref:rgant.adoc#_rgant-ActionLayout_cssClassFa[`@ActionLayout#cssClassFa()`] and xref:rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout#cssClass()`] you can instead specify the UI hint globally using regular expressions.
+Rather than annotating every action with xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClassFa[`@ActionLayout#cssClassFa()`] and xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout#cssClass()`] you can instead specify the UI hint globally using regular expressions.
 
-The xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.reflector.facet.cssClassFa.patterns` is a comma separated list of key:value pairs, eg:
+The xref:../rgcfg/rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.reflector.facet.cssClassFa.patterns` is a comma separated list of key:value pairs, eg:
 
 [source,ini]
 ----
@@ -40,7 +40,7 @@ isis.reflector.facet.cssClassFa.patterns=\
 where the key is a regex matching action names (eg `create.*`) and the value is a link:http://fortawesome.github.io/Font-Awesome/icons/[font-awesome] icon name (eg `fa-plus`) to be applied (as per `@CssClassFa()`) to all action members matching the regex.
 
 
-Similarly, the xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.reflector.facet.cssClass.patterns` is a comma separated list of key:value pairs, eg:
+Similarly, the xref:../rgcfg/rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.reflector.facet.cssClass.patterns` is a comma separated list of key:value pairs, eg:
 
 [source,ini]
 ----
@@ -52,7 +52,7 @@ where (again)the key is a regex matching action names (eg `delete.*`) and the va
 
 [TIP]
 ====
-We strongly recommend that you use this technique rather than annotating each action with xref:rgant.adoc#_rgant-ActionLayout_cssClassFa[`@ActionLayout#cssClassFa()`] or xref:rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout#cssClass()`].  Not only is the code more maintainable, you'll also find that it forces you to be consistent in your action names.
+We strongly recommend that you use this technique rather than annotating each action with xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClassFa[`@ActionLayout#cssClassFa()`] or xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout#cssClass()`].  Not only is the code more maintainable, you'll also find that it forces you to be consistent in your action names.
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_names-and-descriptions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_names-and-descriptions.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_names-and-descriptions.adoc
index cf1bcda..17a908a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_names-and-descriptions.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_names-and-descriptions.adoc
@@ -12,29 +12,29 @@ NOTE: see also xref:ugbtb.adoc#_ugbtb_i18n[Internationalization]
 
 == Class (object)
 
-NOTE: FIXME - xref:rgant.adoc#_rgant-DomainObjectLayout_named[`@DomainObjectLayout#named()`], xref:rgant.adoc#_rgant-DomainObjectLayout_describedAs[`@DomainObjectLayout#describedAs()`]
+NOTE: FIXME - xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_named[`@DomainObjectLayout#named()`], xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_describedAs[`@DomainObjectLayout#describedAs()`]
 
 
 == Property
 
-NOTE: FIXME - xref:rgant.adoc#_rgant-PropertyLayout_named[`@PropertyLayout#named()`], xref:rgant.adoc#_rgant-PropertyLayout_describedAs[`@PropertyLayout#describedAs()`]
+NOTE: FIXME - xref:../rgant/rgant.adoc#_rgant-PropertyLayout_named[`@PropertyLayout#named()`], xref:../rgant/rgant.adoc#_rgant-PropertyLayout_describedAs[`@PropertyLayout#describedAs()`]
 
 
 
 == Collections
 
-NOTE: FIXME - xref:rgant.adoc#_rgant-CollectionLayout_named[`@CollectionLayout#named()`], xref:rgant.adoc#_rgant-CollectionLayout_describedAs[`@CollectionLayout#describedAs()`]
+NOTE: FIXME - xref:../rgant/rgant.adoc#_rgant-CollectionLayout_named[`@CollectionLayout#named()`], xref:../rgant/rgant.adoc#_rgant-CollectionLayout_describedAs[`@CollectionLayout#describedAs()`]
 
 
 
 == Actions
 
-NOTE: FIXME - xref:rgant.adoc#_rgant-ActionLayout_named[`@ActionLayout#named()`], xref:rgant.adoc#_rgant-ActionLayout_describedAs[`@ActionLayout#describedAs()`]
+NOTE: FIXME - xref:../rgant/rgant.adoc#_rgant-ActionLayout_named[`@ActionLayout#named()`], xref:../rgant/rgant.adoc#_rgant-ActionLayout_describedAs[`@ActionLayout#describedAs()`]
 
 
 == Action Parameters
 
-NOTE: FIXME - xref:rgant.adoc#_rgant-ParameterLayout_named[`@ParameterLayout#named()`], xref:rgant.adoc#_rgant-ParameterLayout_describedAs[`@ParameterLayout#describedAs()`]
+NOTE: FIXME - xref:../rgant/rgant.adoc#_rgant-ParameterLayout_named[`@ParameterLayout#named()`], xref:../rgant/rgant.adoc#_rgant-ParameterLayout_describedAs[`@ParameterLayout#describedAs()`]
 
 
 [TIP]

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_object-titles-and-icons.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_object-titles-and-icons.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_object-titles-and-icons.adoc
index 4b91955..6af3a1b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_object-titles-and-icons.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_object-titles-and-icons.adoc
@@ -21,7 +21,7 @@ The title is always shown with an icon, so there is generally no need for the ti
 
 === Declarative style
 
-The xref:rgant.adoc#_rgant-Title[`@Title`] annotation can be used build up the title of an object from its constituent parts.
+The xref:../rgant/rgant.adoc#_rgant-Title[`@Title`] annotation can be used build up the title of an object from its constituent parts.
 
 For example:
 
@@ -75,7 +75,7 @@ Titles can sometimes get be long and therefore rather cumbersome in "parented" t
 
 === Imperative style
 
-NOTE: FIXME - see xref:rgcms.adoc#_rgcms_methods_reserved_title[`title()`]
+NOTE: FIXME - see xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_title[`title()`]
 
 
 
@@ -84,7 +84,7 @@ NOTE: FIXME - see xref:rgcms.adoc#_rgcms_methods_reserved_title[`title()`]
 
 The icon is often the same for all instances of a particular class, but it's also possible for an individual instance to return a custom icon.  This could represent the state of that object (eg a shipped order, say, or overdue library book).
 
-NOTE: FIXME - xref:rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`], xref:rgant.adoc#_rgant-DomainObjectLayout_cssClassFa[`@DomainObjectLayout#cssClassFa()`]
+NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`], xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_cssClassFa[`@DomainObjectLayout#cssClassFa()`]
 
 
 
@@ -92,6 +92,6 @@ NOTE: FIXME - xref:rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`], xr
 == Object CSS Styling
 
 
-It is also possible for an object to return a xref:rgcms.adoc#_rgcms_methods_reserved_cssClass[CSS class].  In conjunction with xref:ugvw.adoc#_ugvw_customisation_tweaking-css-classes[customized CSS] this can be used to apply arbitrary styling; for example each object could be rendered in a page with a different background colour.
+It is also possible for an object to return a xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_cssClass[CSS class].  In conjunction with xref:ugvw.adoc#_ugvw_customisation_tweaking-css-classes[customized CSS] this can be used to apply arbitrary styling; for example each object could be rendered in a page with a different background colour.
 
-NOTE: FIXME - xref:rgcms.adoc#_rgcms_methods_reserved_cssClass[`cssClass()`], xref:rgant.adoc#_rgant-DomainObjectLayout_cssClass[`@DomainObjectLayout#cssClass()`] xref:rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout#cssClass()`], xref:rgant.adoc#_rgant-PropertyLayout_cssClass[`@PropertyLayout#cssClass()`], xref:rgant.adoc#_rgant-CollectionLayout_cssClass[`@CollectionLayout#cssClass()`]
+NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_cssClass[`cssClass()`], xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_cssClass[`@DomainObjectLayout#cssClass()`] xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout#cssClass()`], xref:../rgant/rgant.adoc#_rgant-PropertyLayout_cssClass[`@PropertyLayout#cssClass()`], xref:../rgant/rgant.adoc#_rgant-CollectionLayout_cssClass[`@CollectionLayout#cssClass()`]

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui_are-you-sure.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui_are-you-sure.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui_are-you-sure.adoc
index 5664a55..06dc559 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui_are-you-sure.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui_are-you-sure.adoc
@@ -10,7 +10,7 @@ end-user explicitly confirms that they intended to invoke the action.
 
 == Using action semantics
 
-One way to meet this requirement is using the framework's built-in xref:rgant.adoc#_rgant-Action_semantics[`@Action#semantics()`] attribute:
+One way to meet this requirement is using the framework's built-in xref:../rgant/rgant.adoc#_rgant-Action_semantics[`@Action#semantics()`] attribute:
 
 [source,java]
 ----
@@ -73,4 +73,4 @@ public String validateDelete(boolean areYouSure) {
 <1> invalid to return `this` (cannot render a deleted object)
 
 Note that the action itself does not use the boolean parameter, it is only
-used by the supporting xref:rgcms.adoc#_rgcms_methods_prefixes_validate[`validate...()`] method.
\ No newline at end of file
+used by the supporting xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_validate[`validate...()`] method.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugfun/ugfun.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/ugfun.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/ugfun.adoc
index 1379b7a..6a30398 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/ugfun.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/ugfun.adoc
@@ -9,12 +9,12 @@
 [[__ugfun]]
 == Fundamentals
 
-This guide introduces the xref:ugfun.adoc#_ugfun_core-concepts[core concepts] and ideas behind Apache Isis,
-and tells you how to xref:ugfun.adoc#_ugfun_getting-started[get started] with a Maven archetype.
+This guide introduces the xref:../ugfun/ugfun.adoc#_ugfun_core-concepts[core concepts] and ideas behind Apache Isis,
+and tells you how to xref:../ugfun/ugfun.adoc#_ugfun_getting-started[get started] with a Maven archetype.
 
-It also describes a number of xref:ugfun.adoc#_ugfun_how-tos[how-to]s, describes how to influence the
+It also describes a number of xref:../ugfun/ugfun.adoc#_ugfun_how-tos[how-to]s, describes how to influence the
 xref:ugvw.adoc#_ugvw_layout[UI layout] of your domain objects (this is ultimately just a type of metadata), and it
- catalogues various xref:dg.adoc#_dg_hints-and-tips.adoc[FAQ]s.
+ catalogues various xref:../dg/dg.adoc#_dg_hints-and-tips.adoc[FAQ]s.
 
 === Other Guides
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_disabling-persistence-by-reachability.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_disabling-persistence-by-reachability.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_disabling-persistence-by-reachability.adoc
index 2131664..7fe2432 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_disabling-persistence-by-reachability.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_disabling-persistence-by-reachability.adoc
@@ -14,7 +14,7 @@ However, convenient though this feature is, you may find that it causes performa
 DataNucleus' persistence-by-reachability may cause performance issues.  We strongly recommend that you disable it.
 ====
 
-One scenario in particular where this performance issues can arise is if your entities implement the `java.lang.Comparable` interface, and you have used Apache Isis' xref:rgcms.adoc#_rgcms_classes_utility_ObjectContracts[`ObjectContracts`] utility class. The issue here is that `ObjectContracts` implementation can cause DataNucleus to recursively rehydrate a larger number of associated entities. (More detail below).
+One scenario in particular where this performance issues can arise is if your entities implement the `java.lang.Comparable` interface, and you have used Apache Isis' xref:../rgcms/rgcms.adoc#_rgcms_classes_utility_ObjectContracts[`ObjectContracts`] utility class. The issue here is that `ObjectContracts` implementation can cause DataNucleus to recursively rehydrate a larger number of associated entities. (More detail below).
 
 We therefore recommend that you disable persistence-by-reachability by adding the following to `persistor_datanucleus.properties`:
 
@@ -23,7 +23,7 @@ We therefore recommend that you disable persistence-by-reachability by adding th
 isis.persistor.datanucleus.impl.datanucleus.persistenceByReachabilityAtCommit=false
 ----
 
-This change has been made to the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]
+This change has been made to the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]
 
 If you do disable this feature, then you will (of course) need to ensure that you explicitly persist all entities using the `DomainObjectContainer#persist(.)` or `DomainObjectContainer#persistIfNotAlready(.)` methods.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_eagerly-registering-entities.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_eagerly-registering-entities.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_eagerly-registering-entities.adoc
index 5120578..c947ae6 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_eagerly-registering-entities.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_eagerly-registering-entities.adoc
@@ -14,7 +14,7 @@ Apache Isis is quite happy for the metamodel to be lazily created, and - to be f
 
 The framework thus provide mechanisms to search for all `@PersistenceCapable` entities under specified package(s), and registers them all eagerly.  In fact there are two:
 
-* as of 1.9.0 the recommended (and simpler) approach is to specify an xref:rgcms.adoc#_rgcms_classes_super_AppManifest[`AppManifest`], either as a xref:rgcfg.adoc#_rgcfg_configuring-components[`isis.appManifest`] configuration property or programmatically.
+* as of 1.9.0 the recommended (and simpler) approach is to specify an xref:../rgcms/rgcms.adoc#_rgcms_classes_super_AppManifest[`AppManifest`], either as a xref:../rgcfg/rgcfg.adoc#_rgcfg_configuring-components[`isis.appManifest`] configuration property or programmatically.
 
 * for earlier versions the `isis.persistor.datanucleus.RegisterEntities.packagePrefix` configuration property can be specified.  To bootstrap as a webapp this is usually specified in `persistor_datanucleus.properties`.  (This is also supported in 1.9.0 if no `AppManifest` is specified.  For integration testing this can be specified programatically.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_properties.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_properties.adoc
index 97aee07..ff1be04 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_properties.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_properties.adoc
@@ -30,7 +30,7 @@ These configuration properties are typically stored in `WEB-INF/persistor_datanu
 |fully qualified package names (CSV)
 |that specifies the entities early rather than allow DataNucleus to find the entities lazily.  Further xref:ugodn.adoc#_ugodn_configuring_eagerly-registering-entities[discussion below].
 
-This property is IGNORED if the xref:rgcfg.adoc#_rgcfg_configuring-components[`isis.appManifest`] configuration property is specified, or if an xref:rgcms.adoc#_rgcms_classes_super_AppManifest[`AppManifest`] is provided programmatically.
+This property is IGNORED if the xref:../rgcfg/rgcfg.adoc#_rgcfg_configuring-components[`isis.appManifest`] configuration property is specified, or if an xref:../rgcms/rgcms.adoc#_rgcms_classes_super_AppManifest[`AppManifest`] is provided programmatically.
 
 
 |`isis.persistor.datanucleus.` +

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_overriding-jdo-annotations.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_overriding-jdo-annotations.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_overriding-jdo-annotations.adoc
index d883cc7..fa959f9 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_overriding-jdo-annotations.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_overriding-jdo-annotations.adoc
@@ -43,7 +43,7 @@ This file should be placed can be placed in `src/main/java/META-INF` within your
 
 [TIP]
 ====
-You can use a mixin action on xref:rgcms.adoc#_rgcms_classes_mixins_Persistable[`Persistable`] mixin
+You can use a mixin action on xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins_Persistable[`Persistable`] mixin
 to download the JDO class metadata in XML form.
 ====
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_api-for-applications.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_api-for-applications.adoc b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_api-for-applications.adoc
index 65c1172..6bfb7ec 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_api-for-applications.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_api-for-applications.adoc
@@ -13,7 +13,7 @@ Still, on very rare occasion you may have a need, in which case you can either u
 
 == `DomainObjectContainer` API
 
-The xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`] service exposes the following API:
+The xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`] service exposes the following API:
 
 [source,java]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_configuring-isis-to-use-shiro.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_configuring-isis-to-use-shiro.adoc b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_configuring-isis-to-use-shiro.adoc
index 80c130b..62645cd 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_configuring-isis-to-use-shiro.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_configuring-isis-to-use-shiro.adoc
@@ -9,7 +9,7 @@ Apache Isis' security mechanism is configurable, specifying an `Authenticator` a
 
 [TIP]
 ====
-The xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] is pre-configured to use Apache Shiro, so much of what follows is set up already.
+The xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] is pre-configured to use Apache Shiro, so much of what follows is set up already.
 ====
 
 == Telling Apache Isis to use Shiro

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-ini-realm.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-ini-realm.adoc b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-ini-realm.adoc
index 1d6c92a..306ecb3 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-ini-realm.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-ini-realm.adoc
@@ -7,7 +7,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:ugfun.adoc#_ugfun_getting-started_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:../ugfun/ugfun.adoc#_ugfun_getting-started_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/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_usage-by-isis-viewers.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_usage-by-isis-viewers.adoc b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_usage-by-isis-viewers.adoc
index 90c3bf2..06c3dab 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_usage-by-isis-viewers.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_usage-by-isis-viewers.adoc
@@ -6,7 +6,7 @@
 
 
 
-By and large the security mechanisms within Isis are transparent to the rest of the framework (the xref:ugvw.adoc#[Wicket Viewer] and xref:ugvro.adoc#[Restful Objects viewer], and the overall xref:rgcfg.adoc#_rgcfg[runtime]).
+By and large the security mechanisms within Isis are transparent to the rest of the framework (the xref:ugvw.adoc#[Wicket Viewer] and xref:ugvro.adoc#[Restful Objects viewer], and the overall xref:../rgcfg/rgcfg.adoc#_rgcfg[runtime]).
 
 That said, it is the responsibility of the viewers to ensure that there is a viewers to ensure that for each request there is a valid user session present.  The sections below explain how this works.
 
@@ -56,7 +56,7 @@ As well as providing a sign-in screen, the Wicket viewer also provides the abili
 The sign-in verification page to render is pluggable; see xref:ugvw.adoc#_ugvw_extending_custom-pages[extensions chapter] for details.
 ====
 
-User registration is only available if the xref:rgsvc.adoc#_rgsvc_spi_UserRegistrationService[`UserRegistrationService`] is configured; this is used by the framework to actually create new instances of the user as accessed by the corresponding (Shiro) realm.
+User registration is only available if the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UserRegistrationService[`UserRegistrationService`] is configured; this is used by the framework to actually create new instances of the user as accessed by the corresponding (Shiro) realm.
 
 Because Shiro realms are pluggable, the Apache Isis framework does not provide default implementations of this service.  However, if you are using the http://github.com/isisaddons/isis-module-security[Isis addons' security] module (non-ASF), then this module _does_ provide an implementation (that, as you might expect, creates new "user" domain entities).
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugsec/ugsec.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugsec/ugsec.adoc b/adocs/documentation/src/main/asciidoc/guides/ugsec/ugsec.adoc
index dee8d17..b12e3c7 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugsec/ugsec.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugsec/ugsec.adoc
@@ -53,7 +53,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:ugfun.adoc#_ugfun_getting-started_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:../ugfun/ugfun.adoc#_ugfun_getting-started_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.  Apache Isis in turn extends this with its `IsisLdapRealm`, which provides more flexibility for both group/role and role/permissions management.
 
@@ -66,16 +66,16 @@ In addition to Apache Isis' Shiro-based implementation of its authentication and
 ====
 A further aspect of security is auditing: recording what data was modified by which user.
 
-Apache Isis provides the xref:rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`]
-can be used to track the actions being invoked, and the xref:rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditerService`]
+Apache Isis provides the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`]
+can be used to track the actions being invoked, and the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditerService`]
 captures what data was modified as a result (auditing).  When ``Interaction``s are persisted (eg by way of
 (non-ASF) http://github.com/isisaddons/isis-module-publishmq[Isis addons' publishmq] module) this provides excellent
 traceability.  The (non-ASF) http://github.com/isisaddons/isis-module-audit[Isis addons' audit] module provides an
 implementation of the `AuditerService`.
 
 For earlier versions of the framework the
-xref:rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] can be used to capture actions, while the (deprecated)
-xref:rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`] used to capture data modified.
+xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] can be used to capture actions, while the (deprecated)
+xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`] used to capture data modified.
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_bdd-spec-support_maven-configuration.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_bdd-spec-support_maven-configuration.adoc b/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_bdd-spec-support_maven-configuration.adoc
index c3e0073..7febe87 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_bdd-spec-support_maven-configuration.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_bdd-spec-support_maven-configuration.adoc
@@ -7,7 +7,7 @@
 
 
 
-Apache Isis' BDD spec support is automatically configured if you use the xref:ugfun.adoc#_ugfun_getting-started_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:../ugfun/ugfun.adoc#_ugfun_getting-started_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/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_bdd-spec-support_writing-a-bdd-spec.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_bdd-spec-support_writing-a-bdd-spec.adoc b/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_bdd-spec-support_writing-a-bdd-spec.adoc
index b22f292..cc5246d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_bdd-spec-support_writing-a-bdd-spec.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_bdd-spec-support_writing-a-bdd-spec.adoc
@@ -24,7 +24,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:ugtst.adoc#_ugtst_integ-test-support[Integration Test Support], bootstrapping section).
 
 
-Here's an example of a feature from the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]:
+Here's an example of a feature from the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]:
 
 [source,java]
 ----
@@ -49,7 +49,7 @@ Apache Isis does also support running BDD specs in unit test mode; by annotating
 
 To support unit testing scope Apache 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:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].  For those who do require faster-executing test suite, it's worthwhile knowing that Apache 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:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].  For those who do require faster-executing test suite, it's worthwhile knowing that Apache Isis can support this.
 
 ====
 
@@ -72,7 +72,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:ugfun.adoc#_ugfun_getting-started_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:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
 
 The bootstrapping of Apache Isis can be moved into a `BootstrappingGlue` step definition:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_fixture-scripts_api-and-usage.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_fixture-scripts_api-and-usage.adoc b/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_fixture-scripts_api-and-usage.adoc
index d7ab650..b94a39a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_fixture-scripts_api-and-usage.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_fixture-scripts_api-and-usage.adoc
@@ -19,11 +19,11 @@ There are two ways in which you can provide a `FixtureScripts` service.
 
 The original (pre-1.9.0) approach is to subclass subclass `FixtureScripts` domain service, with your subclass specifying which package to search for.  Various other settings can also be provided, and - being a custom class - you can also add in additional actions.  A common example is to provide a "one-shot" action to recreate a standard demo set of objects.
 
-As of 1.9.0 there is an alternative design.  Instead of subclassing `FixtureScripts` you instead implement the xref:rgsvc.adoc#_rgsvc_spi_FixtureScriptsSpecificationProvider[`FixtureScriptsSpecificationProvider`] SPI.  (As its name suggests), this provides a `FixtureScriptsSpecification` object that contains the same information as would otherwise have been in the `FixtureScripts` subclass.
+As of 1.9.0 there is an alternative design.  Instead of subclassing `FixtureScripts` you instead implement the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_FixtureScriptsSpecificationProvider[`FixtureScriptsSpecificationProvider`] SPI.  (As its name suggests), this provides a `FixtureScriptsSpecification` object that contains the same information as would otherwise have been in the `FixtureScripts` subclass.
 
-The actual implementation of the `FixtureScripts` service is then provided by the framework itself, namely the xref:rgsvc.adoc#_rgsvc_api_FixtureScriptsDefault[`FixtureScriptsDefault`] domain service, annotated to be rendered on the secondary "Prototyping" menu.  This uses the `FixtureScriptsSpecificationProvider` to adjust itself accordinly.
+The actual implementation of the `FixtureScripts` service is then provided by the framework itself, namely the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_FixtureScriptsDefault[`FixtureScriptsDefault`] domain service, annotated to be rendered on the secondary "Prototyping" menu.  This uses the `FixtureScriptsSpecificationProvider` to adjust itself accordinly.
 
-For example, here's the `FixtureScriptsSpecificationProvider` service that's generated by the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]:
+For example, here's the `FixtureScriptsSpecificationProvider` service that's generated by the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]:
 
 [source,java]
 ----
@@ -113,7 +113,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:ugfun.adoc#_ugfun_getting-started_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:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] adds this additional action:
 
 [source,java]
 ----
@@ -139,7 +139,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:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]:
+Here's the `RecreateSimpleObjects` fixture script from the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]:
 
 [source,java]
 ----
@@ -236,7 +236,7 @@ public class SimpleObjectCreate extends FixtureScript {       // <1>
 <3> output property: the created simple object
 <4> the mandatory execute(...) API
 <5> the `checkParam(...)` (inherited from `FixtureScript`) will check that the "name" property has been populated (using Java's Reflection API) and throw an exception if not
-<6> wrap the injected `SimpleObjects` domain service (using the xref:rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`]) to simulate interaction through the UI...
+<6> wrap the injected `SimpleObjects` domain service (using the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`]) to simulate interaction through the UI...
 <7> .. and actually create the object using the "create" business action of that service
 <8> add the resulting object to the execution context; this makes the object available to access if run from the UI
 <9> inject the domain service into the fixture script
@@ -251,7 +251,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:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]:
+For example, here's an integration test from the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]:
 
 [source,java]
 ----
@@ -296,7 +296,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:ugfun.adoc#_ugfun_getting-started_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:../ugfun/ugfun.adoc#_ugfun_getting-started_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].
 
@@ -318,7 +318,7 @@ image::{_imagesdir}testing/fixture-scripts/composite.png[width="550px",link="{_i
 
 Back in the earlier 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:ugfun.adoc#_ugfun_getting-started_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:../ugfun/ugfun.adoc#_ugfun_getting-started_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/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_integ-test-support_bootstrapping.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_integ-test-support_bootstrapping.adoc b/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_integ-test-support_bootstrapping.adoc
index 41f194b..8ce55e3 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_integ-test-support_bootstrapping.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_integ-test-support_bootstrapping.adoc
@@ -9,9 +9,9 @@ Integration tests instantiate an Apache Isis "runtime" (as a singleton) within a
 
 Nevertheless, we do need to bootstrap the runtime for the very first test.
 
-As of 1.9.0 the bootstrapping of integration tests and webapps has been simplified through the xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`] class.  Since this isn't mandatory, for now we present both techniques.
+As of 1.9.0 the bootstrapping of integration tests and webapps has been simplified through the xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`] class.  Since this isn't mandatory, for now we present both techniques.
 
-The example code in this section is taken from the app generated by the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
+The example code in this section is taken from the app generated by the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
 
 
 
@@ -95,7 +95,7 @@ public class DomainAppAppManifest implements AppManifest {
 }
 ----
 
-Further details on bootstrapping with the `AppManifest` can be found in the xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[reference guide].
+Further details on bootstrapping with the `AppManifest` can be found in the xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[reference guide].
 
 === 1.8.0 and earlier
 
@@ -302,15 +302,15 @@ The `IntegrationTestAbstract` also provides a number of helper/convenience metho
 deprecated because the functionality they expose is now readily accessible through various domain services; most
 notably these are:
 
-* xref:rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`] +
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`] +
 +
 to wrap objects simulating interaction through the user interface)
 
-* xref:rgsvc.adoc#_rgsvc_api_TransactionService[`TransactionService`] +
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_TransactionService[`TransactionService`] +
 +
 most commonly used to commit changes after the fixture setup) and,
 
-* xref:rgsvc.adoc#_rgsvc_api_SessionManagementService[`SessionManagementService`] +
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_SessionManagementService[`SessionManagementService`] +
 +
 for tests that check interactions over multiple separate sessions.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_integ-test-support_maven-configuration.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_integ-test-support_maven-configuration.adoc b/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_integ-test-support_maven-configuration.adoc
index c6aa492..7b98813 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_integ-test-support_maven-configuration.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_integ-test-support_maven-configuration.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-Apache Isis' integration test support is automatically configured if you use the xref:ugfun.adoc#_ugfun_getting-started_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:../ugfun/ugfun.adoc#_ugfun_getting-started_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/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_integ-test-support_typical-usage.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_integ-test-support_typical-usage.adoc b/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_integ-test-support_typical-usage.adoc
index a201287..ea919cf 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_integ-test-support_typical-usage.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_integ-test-support_typical-usage.adoc
@@ -58,7 +58,7 @@ public class ToDoItemIntegTest extends AbstractToDoIntegTest {
     ...
 }
 ----
-<1> the xref:rgcms.adoc#_rgcms_classes_super_FixtureScripts[`FixtureScripts`] domain service is injected, providing us with the ability to run fixture scripts
+<1> the xref:../rgcms/rgcms.adoc#_rgcms_classes_super_FixtureScripts[`FixtureScripts`] domain service is injected, providing us with the ability to run fixture scripts
 <2> likewise, an instance of the `ToDoItems` domain service is injected.  We'll use this to lookup...
 <3> the object under test, held as a field
 <4> the fixture script for this test; it deletes all existing todo items (for the current user only) and then recreates them

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_integ-test-support_wrapper-factory.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_integ-test-support_wrapper-factory.adoc b/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_integ-test-support_wrapper-factory.adoc
index 5c9a6a6..cfaa0be 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_integ-test-support_wrapper-factory.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_integ-test-support_wrapper-factory.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-The xref:rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`] service is responsible for wrapping a domain object in a dynamic proxy, of the same type as the object being proxied.  And the role of this wrapper is to simulate the UI.
+The xref:../rgsvc/rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`] service is responsible for wrapping a domain object in a dynamic proxy, of the same type as the object being proxied.  And the role of this wrapper is to simulate the UI.
 
 [NOTE]
 ====
@@ -145,7 +145,7 @@ public void subscriberReceivesEvents() throws Exception {
     then(evHolder[0].getIdentifier().getMemberName()).isEqualTo("completed");
 }
 ----
-<1> inject xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] into this test
+<1> inject xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] into this test
 <2> holder for subscriber to capture event to
 <3> subscriber's callback, using the guava subscriber syntax
 <4> invoking the domain object using the wrapper

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_overview.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_overview.adoc b/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_overview.adoc
index bac084e..08d6384 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_overview.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_overview.adoc
@@ -52,7 +52,7 @@ When we talk about integration tests/specs here, we mean tests that exercise the
 
 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://docs.seleniumhq.org/[Selenium], driving a web browser to navigate .  In this regard though, Apache Isis has a significant trick up its sleeve.  Because Apache 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:rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`] domain service allows a test to wrap domain objects and thus to interact with said objects "as if" through the UI:
+The xref:../rgsvc/rgsvc.adoc#_rgsvc_api_WrapperFactory[`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"]
 
@@ -125,7 +125,7 @@ In the previous section we discussed using given/when/then as a form of organizi
 
 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 Apache Isis provides is a domain service called xref:rgcms.adoc#_rgcms_classes_super_FixtureScripts[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.
+The solution that Apache Isis provides is a domain service called xref:../rgcms/rgcms.adoc#_rgcms_classes_super_FixtureScripts[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.
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_unit-test-support_contract-tests.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_unit-test-support_contract-tests.adoc b/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_unit-test-support_contract-tests.adoc
index 5caa1fa..c9f8569 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_unit-test-support_contract-tests.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_unit-test-support_contract-tests.adoc
@@ -41,7 +41,7 @@ If using DataNucleus against an RDBMS (as you probably are) then we strongly rec
 
 * second, `SortedSet` is preferable to `Set` because then the order is well-defined and predictable (to an end user, to the programmer). +
 +
-The xref:rgcms.adoc#_rgcms_classes_utility_ObjectContracts[`ObjectContracts`]  utility class substantially simplifies the task of implementing `Comparable` in your domain classes.
+The xref:../rgcms/rgcms.adoc#_rgcms_classes_utility_ObjectContracts[`ObjectContracts`]  utility class substantially simplifies the task of implementing `Comparable` in your domain classes.
 
 * third, if the relationship is bidirectional then JDO/Objectstore will automatically maintain the relationship.
 
@@ -64,11 +64,11 @@ public class SortedSetsContractTestAll extends SortedSetsContractTestAbstract {
 
 == Bidirectional
 
-This contract test automatically checks that bidirectional 1:m or 1:1 associations are being maintained correctly (assuming that they follow the xref:ugfun.adoc#_ugfun_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships[mutual registration pattern]
+This contract test automatically checks that bidirectional 1:m or 1:1 associations are being maintained correctly (assuming that they follow the xref:../ugfun/ugfun.adoc#_ugfun_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships[mutual registration pattern]
 
 [TIP]
 ====
-(If using the JDO objectstore, then) there is generally no need to programmatically maintain 1:m relationships (indeed it may introduce subtle errors). For more details, see xref:ugfun.adoc#_ugfun_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships[here].  Also check out the templates in the developers' guide (xref:dg.adoc#__dg_ide_intellij_live-templates[live templates for IntelliJ] / xref:dg.adoc#__dg_ide_eclipse_editor-templates[editor templates for Eclipse]) for further guidance.
+(If using the JDO objectstore, then) there is generally no need to programmatically maintain 1:m relationships (indeed it may introduce subtle errors). For more details, see xref:../ugfun/ugfun.adoc#_ugfun_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships[here].  Also check out the templates in the developers' guide (xref:../dg/dg.adoc#__dg_ide_intellij_live-templates[live templates for IntelliJ] / xref:../dg/dg.adoc#__dg_ide_eclipse_editor-templates[editor templates for Eclipse]) for further guidance.
 ====
 
 For example, suppose that `ParentDomainObject` and `ChildDomainObject` have a 1:m relationship (`ParentDomainObject#children` / `ChildDomainObject#parent`), and also `PeerDomainObject` has a 1:1 relationship with itself (`PeerDomainObject#next` / `PeerDomainObject#previous`).

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_unit-test-support_maven-configuration.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_unit-test-support_maven-configuration.adoc b/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_unit-test-support_maven-configuration.adoc
index 1a8f806..d6bd084 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_unit-test-support_maven-configuration.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_unit-test-support_maven-configuration.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-Apache Isis' unit test support is automatically configured if you use the xref:ugfun.adoc#_ugfun_getting-started_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:../ugfun/ugfun.adoc#_ugfun_getting-started_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/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_architecture.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_architecture.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_architecture.adoc
index 8668474..24c3228 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_architecture.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_architecture.adoc
@@ -17,7 +17,7 @@ the `Content-Type` header which the client can use to know how to process the re
 
 * `RepresentationService` +
 +
-The xref:rgfis.adoc#_rgfis_spi_RepresentationService[`RepresentationService`] is an SPI domain service (plugin-point)
+The xref:../rgfis/rgfis.adoc#_rgfis_spi_RepresentationService[`RepresentationService`] is an SPI domain service (plugin-point)
 that allows an arbitrary representation to be generated for any of the resources defined in the RO spec. +
 +
 Normally this SPI service need not be replaced, because the default implementation
@@ -29,7 +29,7 @@ is able to handle the request (per the chain of responsibliity pattern).
 * `ContentNegotiationService` +
 +
 As noted above, there can be multiple implementations of the
-xref:rgfis.adoc#_rgfis_spi_ContentNegotiationService[`ContentNegotiationService`], each one handling a particular
+xref:../rgfis/rgfis.adoc#_rgfis_spi_ContentNegotiationService[`ContentNegotiationService`], each one handling a particular
 HTTP `Accept` header.  If the implementation does not recognize the value of the header, if can simply return `null`. +
 +
 The framework provides a number of implementations; an implementation that handles the
@@ -38,7 +38,7 @@ default/fallback implementation that returns the representations defined by the
 
 * `ContentMappingService` +
 +
-The xref:rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`] is used by the implementation of
+The xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`] is used by the implementation of
 `ContentNegotationService` that recognizes the `x-ro-domain-type`, its role being to transform a domain object
 (usually an entity) into some other form (usually a DTO), as specified by the `x-ro-domain-type` parameter.  There
 can be many such implementations, each handling a different target domain type.

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips.adoc
index 24ccb2e..ac454f9 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips.adoc
@@ -88,7 +88,7 @@ Use `$resource.put(...)` or `$resource.post(...)` instead.
 
 == Pretty printing
 
-The JSON representations generated by the Restful Objects viewer are in compact form if the xref:rgcfg.adoc#_rgcfg_deployment-types[deployment type] is SERVER (ie production), but will automatically be "pretty printed" (in other words indented) if the deployment type is PROTOTYPE.
+The JSON representations generated by the Restful Objects viewer are in compact form if the xref:../rgcfg/rgcfg.adoc#_rgcfg_deployment-types[deployment type] is SERVER (ie production), but will automatically be "pretty printed" (in other words indented) if the deployment type is PROTOTYPE.
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_ro-spec.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_ro-spec.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_ro-spec.adoc
index 4a16f97..ff033e5 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_ro-spec.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_ro-spec.adoc
@@ -130,7 +130,7 @@ For example, the client could use an `Accept` header such as:
 Accept: application/xml;x-ro-domain-type="com.mycompany.viewmodels.v2.CustomerViewModel"
 ----
 
-The server will use the xref:rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`] to attempt to
+The server will use the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`] to attempt to
 transform the domain object into the requested `x-ro-domain-type`.  The whole process is discussed in more detail in
 the xref:ugvro.adoc#_ugvro_architecture[architecture] chapter.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_configuration-properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_configuration-properties.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_configuration-properties.adoc
index 0326396..c33b46c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_configuration-properties.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_configuration-properties.adoc
@@ -99,7 +99,7 @@ for further details).
 |`isis.viewer.wicket.` +
 `liveReloadUrl`
 | URL
-|Specifies the URL if xref:dg.adoc#__dg_ide_intellij_advanced_gradle-liveReload[live reload] is set up, eg: +
+|Specifies the URL if xref:../dg/dg.adoc#__dg_ide_intellij_advanced_gradle-liveReload[live reload] is set up, eg: +
 
 `http://localhost:35729/livereload.js?snipver=1`
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_customisation_about-page.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_customisation_about-page.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_customisation_about-page.adoc
index e2450bb..7218453 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_customisation_about-page.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_customisation_about-page.adoc
@@ -31,7 +31,7 @@ If none of these are found, then no version is displayed.
 
 [TIP]
 ====
-This configuration is included within the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
+This configuration is included within the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
 ====
 
 === Adding attributes to the WAR's manifest

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_customisation_brand-logo.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_customisation_brand-logo.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_customisation_brand-logo.adoc
index aafbd15..ed6a321 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_customisation_brand-logo.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_customisation_brand-logo.adoc
@@ -56,7 +56,7 @@ protected Module newIsisWicketModule() {
 If the logo is hosted locally, add to the relevant directory (eg `src/main/webapp/images`). It is also valid for the
 URL to be absolute.
 
-You may also wish to tweak the xref:rgcfg.adoc#_rgcfg_application-specific_application-css[`application.css`]. For example, a logo with height 40px works well with the following:
+You may also wish to tweak the xref:../rgcfg/rgcfg.adoc#_rgcfg_application-specific_application-css[`application.css`]. For example, a logo with height 40px works well with the following:
 
 [source,css]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_customisation_tweaking-css-classes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_customisation_tweaking-css-classes.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_customisation_tweaking-css-classes.adoc
index fbe0b55..1413b91 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_customisation_tweaking-css-classes.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_customisation_tweaking-css-classes.adoc
@@ -15,7 +15,7 @@ The HTML generated by the Wicket viewer include plenty of CSS classes so that yo
 }
 ----
 
-These customizations should generally be added to xref:rgcfg.adoc#_rgcfg_application-specific_application-css[`application.css]`; this file is included by default in every webpage served up by the Wicket viewer.
+These customizations should generally be added to xref:../rgcfg/rgcfg.adoc#_rgcfg_application-specific_application-css[`application.css]`; this file is included by default in every webpage served up by the Wicket viewer.
 
 
 
@@ -44,7 +44,7 @@ For example, the `ToDoItem` object of the Isis addons example https://github.com
 </div>
 ----
 
-The xref:rgcfg.adoc#_rgcfg_application-specific_application-css[`application.css`] file is the place to add application-specific styles. By way of an example, if (for some reason) we wanted to completely hide the notes value, we could do so using:
+The xref:../rgcfg/rgcfg.adoc#_rgcfg_application-specific_application-css[`application.css`] file is the place to add application-specific styles. By way of an example, if (for some reason) we wanted to completely hide the notes value, we could do so using:
 
 [source,css]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_extending_custom-pages.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_extending_custom-pages.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_extending_custom-pages.adoc
index 6bcc703..1f143c1 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_extending_custom-pages.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_extending_custom-pages.adoc
@@ -20,10 +20,10 @@ Isis defines eight page types (see the `org.apache.isis.viewer.wicket.model.mode
 | The initial sign-in (aka login) page
 
 | SIGN_UP
-| The sign-up page (if xref:rgsvc.adoc#_rgsvc_spi_UserRegistrationService[user registration] is enabled).
+| The sign-up page (if xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UserRegistrationService[user registration] is enabled).
 
 | SIGN_UP_VERIFY
-| The sign-up verification page (if xref:rgsvc.adoc#_rgsvc_spi_UserRegistrationService[user registration] is enabled; as accessed by link from verification email)
+| The sign-up verification page (if xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UserRegistrationService[user registration] is enabled; as accessed by link from verification email)
 
 | PASSWORD_RESET
 | The password reset page (if enabled).

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_features_blob-attachments.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_features_blob-attachments.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_features_blob-attachments.adoc
index 2d2fa69..59579a3 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_features_blob-attachments.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_features_blob-attachments.adoc
@@ -6,7 +6,7 @@
 
 
 
-The Isis application library provides the xref:rgcms.adoc#_rgcms_classes_value-types_Blob[Blob] value type (binary large objects) and also the xref:rgcms.adoc#_rgcms_classes_value-types_Clob[Clob]
+The Isis application library provides the xref:../rgcms/rgcms.adoc#_rgcms_classes_value-types_Blob[Blob] value type (binary large objects) and also the xref:../rgcms/rgcms.adoc#_rgcms_classes_value-types_Clob[Clob]
 value type (character large object), each of which also includes metadata about the data (specifically the filename and mime type).
 
 A class can define a property using either of these types, for example:

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_features_bookmarked-pages.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_features_bookmarked-pages.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_features_bookmarked-pages.adoc
index d0de6d8..9ce7313 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_features_bookmarked-pages.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_features_bookmarked-pages.adoc
@@ -6,7 +6,7 @@
 
 
 
-The Wicket viewer supports the bookmarking of both domain objects and query-only (xref:rgant.adoc#_rgant-Action_semantics[@Action(semantics=...)]) actions.
+The Wicket viewer supports the bookmarking of both domain objects and query-only (xref:../rgant/rgant.adoc#_rgant-Action_semantics[@Action(semantics=...)]) actions.
 
 Domain objects, if bookmarkable, can be nested.
 
@@ -39,7 +39,7 @@ Some - like `Property`, `Lease` and `Party` - are root nodes. However, `LeaseIte
 
 == Domain Code
 
-To indicate a class is bookmarkable, use the xref:rgant.adoc#_rgant-DomainObjectLayout[@DomainObjectLayout] annotation:
+To indicate a class is bookmarkable, use the xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout[@DomainObjectLayout] annotation:
 
 [source,java]
 ----
@@ -59,7 +59,7 @@ To indicate a class is bookmarkable but only as a child of some parent bookmark,
 public class LeaseItem { ... }
 ----
 
-To indicate that a safe (query only) action is bookmarkable, use the xref:rgant.adoc#_rgant-ActionLayout[@ActionLayout] annotation:
+To indicate that a safe (query only) action is bookmarkable, use the xref:../rgant/rgant.adoc#_rgant-ActionLayout[@ActionLayout] annotation:
 
 [source,java]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_features_user-registration.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_features_user-registration.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_features_user-registration.adoc
index c595ae5..c9426f7 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_features_user-registration.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_features_user-registration.adoc
@@ -17,9 +17,9 @@ In a similar way, if the user has forgotten their password then they can request
 
 To support this the framework requires three services to be registered and configured:
 
-* the xref:rgsvc.adoc#_rgsvc_spi_UserRegistrationService[user registration service], which provides an API to create the user account
-* the xref:rgsvc.adoc#_rgsvc_spi_EmailNotificationService[email notification service], which provides an API for to send the verification emails
-* the xref:rgsvc.adoc#_rgsvc_api_EmailService[email service], that is used by the email notification service to actually send the email.
+* the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UserRegistrationService[user registration service], which provides an API to create the user account
+* the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_EmailNotificationService[email notification service], which provides an API for to send the verification emails
+* the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EmailService[email service], that is used by the email notification service to actually send the email.
 
 The Apache Isis core framework provides a default implementation of both the email notification service and the email service. If your application uses the https://github.com/isisaddons/isis-module-security[Isis addons security module] (not ASF) then an implementation is provided by that module; just add to the classpath. Otherwise you will need to provide your own implementation.
 
@@ -68,9 +68,9 @@ image::{_imagesdir}user-registration/sign-up-after-registration.png[width="800px
 
 There are two prerequisites:
 
-* register an implementation of the xref:rgsvc.adoc#_rgsvc_spi_UserRegistrationService[user registration service] (eg by using the https://github.com/isisaddons/isis-module-security[Isis addons security module])
+* register an implementation of the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UserRegistrationService[user registration service] (eg by using the https://github.com/isisaddons/isis-module-security[Isis addons security module])
 
-* configure the xref:rgsvc.adoc#_rgsvc_api_EmailService[email service]
+* configure the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EmailService[email service]
 
 The latter is required if you are using the default email notification service and email service. If you are using your own alternative implementation of the email notification service then it may be omitted (and configure your own alternative implementation as required).
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_annotation-based.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_annotation-based.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_annotation-based.adoc
index b8ec9e5..efc0d0c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_annotation-based.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_annotation-based.adoc
@@ -15,21 +15,21 @@ This section explains how.
 
 == `@MemberOrder`
 
-The xref:rgant.adoc#_rgant-MemberOrder[`@MemberOrder`]  annotation is used to specify the relative order of domain class properties, collections and actions.
+The xref:../rgant/rgant.adoc#_rgant-MemberOrder[`@MemberOrder`]  annotation is used to specify the relative order of domain class properties, collections and actions.
 
-The annotation defines two attributes, xref:rgant.adoc#_rgant-MemberOrder_name[`name()`] and xref:rgant.adoc#_rgant-MemberOrder_sequence[`sequence()`].  Their usage depends on the member type:
+The annotation defines two attributes, xref:../rgant/rgant.adoc#_rgant-MemberOrder_name[`name()`] and xref:../rgant/rgant.adoc#_rgant-MemberOrder_sequence[`sequence()`].  Their usage depends on the member type:
 
 * for properties, the `name()` is used to group properties together into a member group (also called a property group
 or a fieldset.  The `sequence()` then orders properties within these groups. If no `name()` is specified then the
 property is placed in a fallback "General" group, called "General". +
 +
-The name of these member groups/fieldsets are then referenced by xref:rgant.adoc#_rgant-MemberGroupLayout[`@MemberGroupLayout`].
+The name of these member groups/fieldsets are then referenced by xref:../rgant/rgant.adoc#_rgant-MemberGroupLayout[`@MemberGroupLayout`].
 
 * for collections, the `name()` attribute is (currently) unused.  The `sequence()` orders collections relative to one another
 
 * for actions, the `name()` attribute associates an action with either a property or with a collection. +
 
-** If the `name()` attribute matches a property name, then the action's button is rendered close to the property, according to xref:rgant.adoc#_rgant-ActionLayout_position[`@ActionLayout#position()`] attribute. +
+** If the `name()` attribute matches a property name, then the action's button is rendered close to the property, according to xref:../rgant/rgant.adoc#_rgant-ActionLayout_position[`@ActionLayout#position()`] attribute. +
 
 ** On the other hand if the `name() attribute matches a collection name, then the action's button is rendered on the collection's header.
 
@@ -64,7 +64,7 @@ public class ToDoItem {
 
 This defines three property (or member) groups, "General", "Detail" and "Misc"; "General" is the default if no `name` attribute is specified. Properties in the same member group are rendered together, as a fieldset.
 
-In addition, actions can optionally be associated (rendered close to) either properties or actions. This is done by overloading the ``@MemberOrder``'s xref:rgant.adoc#_rgant-MemberOrder_name[`name()`] attribute, holding the value of the property or collection.
+In addition, actions can optionally be associated (rendered close to) either properties or actions. This is done by overloading the ``@MemberOrder``'s xref:../rgant/rgant.adoc#_rgant-MemberOrder_name[`name()`] attribute, holding the value of the property or collection.
 
 For example:
 
@@ -91,7 +91,7 @@ public class ToDoItem {
 will associate the `completed()` and `notYetCompleted()` actions with the `complete` property, and will associate the `add()` and `remove()` actions with the `dependencies` collection.
 
 
-The value of xref:rgant.adoc#_rgant-MemberOrder_sequence[`sequence()`] is a string.  The simplest convention (as shown in the example above) is to use numbers -- 1, 2, 3 -- though it is a better idea to leave gaps in the numbers -- 10, 20, 30 perhaps -- such that a new member may be added without having to edit existing numbers.
+The value of xref:../rgant/rgant.adoc#_rgant-MemberOrder_sequence[`sequence()`] is a string.  The simplest convention (as shown in the example above) is to use numbers -- 1, 2, 3 -- though it is a better idea to leave gaps in the numbers -- 10, 20, 30 perhaps -- such that a new member may be added without having to edit existing numbers.
 
 Even better is to adopt the 'dewey-decimal' notation -- 1, 1.1, 1.2, 2, 3, 5.1.1, 5.2.2, 5.2, 5.3 -- which allows for an indefinite amount of future insertion.  It also allows subclasses to insert their class members as required.
 
@@ -100,7 +100,7 @@ Even better is to adopt the 'dewey-decimal' notation -- 1, 1.1, 1.2, 2, 3, 5.1.1
 
 == `@MemberGroupLayout`
 
-The xref:rgant.adoc#_rgant-MemberGroupLayout[`@MemberGroupLayout`] annotation specifies the relative positioning of property groups/fieldsets as being either in a left column, a middle column or in a right column.  The annotation also specifies the relative width of the columns.
+The xref:../rgant/rgant.adoc#_rgant-MemberGroupLayout[`@MemberGroupLayout`] annotation specifies the relative positioning of property groups/fieldsets as being either in a left column, a middle column or in a right column.  The annotation also specifies the relative width of the columns.
 
 The property groups/fieldsets in this case are those that are inferred from the `@MemberOrder#name()` attribute.
 
@@ -110,7 +110,7 @@ It is also possible to combine `@MemberOrder` with a xref:ugvw.adoc#_ugvw_layout
 The layout file defines only the regions of a grid structure (fieldsets/columns etc), but does __not__ specify the properties/collections/actions within those grid regions.
 The `@MemberOrder` annotation in effect "binds" the properties or collections to those regions of the grid.
 
-When file-based layouts are used this way, the xref:rgant.adoc#_rgant-MemberGroupLayout[`@MemberGroupLayout`] annotation is essentially ignored, but the metadata from the xref:rgant.adoc#_rgant-MemberOrder[`@MemberOrder`] annotation (and the other layout annotations, xref:rgant.adoc#_rgant-ActionLayout[`@ActionLayout`], xref:rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`] and xref:rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`]) are all still honoured.
+When file-based layouts are used this way, the xref:../rgant/rgant.adoc#_rgant-MemberGroupLayout[`@MemberGroupLayout`] annotation is essentially ignored, but the metadata from the xref:../rgant/rgant.adoc#_rgant-MemberOrder[`@MemberOrder`] annotation (and the other layout annotations, xref:../rgant/rgant.adoc#_rgant-ActionLayout[`@ActionLayout`], xref:../rgant/rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`] and xref:../rgant/rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`]) are all still honoured.
 ====
 
 For example:
@@ -174,4 +174,4 @@ image::{_imagesdir}reference-layout/4-0-8-0.png[width="720px",link="{_imagesdir}
 
 == Other Annotations
 
-As of 1.8.0, all the layout annotations have been consolidated into the various `XxxLayout` annotations: xref:rgant.adoc#_rgant-ActionLayout, [`@ActionLayout`] xref:rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`],  xref:rgant.adoc#_rgant-DomainObjectLayout[`@DomainObjectLayout`],  xref:rgant.adoc#_rgant-DomainServiceLayout[`@DomainServiceLayout`],  xref:rgant.adoc#_rgant-ParameterLayout[`@ParameterLayout`], xref:rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`], and xref:rgant.adoc#_rgant-ViewModelLayout[`@ViewModelLayout`]
+As of 1.8.0, all the layout annotations have been consolidated into the various `XxxLayout` annotations: xref:../rgant/rgant.adoc#_rgant-ActionLayout, [`@ActionLayout`] xref:../rgant/rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`],  xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout[`@DomainObjectLayout`],  xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout[`@DomainServiceLayout`],  xref:../rgant/rgant.adoc#_rgant-ParameterLayout[`@ParameterLayout`], xref:../rgant/rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`], and xref:../rgant/rgant.adoc#_rgant-ViewModelLayout[`@ViewModelLayout`]

[07/58] [abbrv] isis git commit: ISIS-1521: fixes xref links between guides

[da...@apache.org]

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_CommandContext.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_CommandContext.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_CommandContext.adoc
index 7334b62..e48d0b0 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_CommandContext.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_CommandContext.adoc
@@ -6,24 +6,24 @@
 
 
 
-The `CommandContext` service is a xref:rgant.adoc#_rgant-RequestScoped[request-scoped] service that reifies the invocation of an action on a domain object into an object itself. This reified information is encapsulated within the `Command` object.
+The `CommandContext` service is a xref:../rgant/rgant.adoc#_rgant-RequestScoped[request-scoped] service that reifies the invocation of an action on a domain object into an object itself. This reified information is encapsulated within the `Command` object.
 
 By default, the `Command` is held in-memory only; once the action invocation has completed, the `Command` object is gone. The optional
- supporting xref:rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] enables the implementation of `Command` to be pluggable. With an appropriate implementation (eg as provided by the (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module's xref:rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`]) the `Command` may then be persisted.
+ supporting xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] enables the implementation of `Command` to be pluggable. With an appropriate implementation (eg as provided by the (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module's xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`]) the `Command` may then be persisted.
 
 As of `1.13.0`, the primary use case for persistent ``Command``s is in support of background commands; they
 act as a parent to any background commands that can be persisted either explicitly using the
-xref:rgsvc.adoc#_rgsvc_api_BackgroundService[`BackgroundService`], or implicitly by way of the
-xref:rgant.adoc#_rgant-Action_command[`@Action#command()`] annotation.
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BackgroundService[`BackgroundService`], or implicitly by way of the
+xref:../rgant/rgant.adoc#_rgant-Action_command[`@Action#command()`] annotation.
 
 In previous versions of the framework, persistent ``Command``s also supported a number of other use cases:
 
 * they enable profiling of the running application (which actions are invoked then most often, what is their response time)
-* if a xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] or xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`] (the latter now deprecated) is configured, they provide better traceability as the `Command` is also correlated with any published events, again through the unique `transactionId` GUID
-* if a xref:rgsvc.adoc#_rgsvc_spi_AuderService[`AuditerService`] or xref:rgsvc.adoc#_rgsvc_spi_AuditService[`AuditingService`] (the latter now deprecated) is configured, they provide better audit information, since the `Command` (the 'cause' of an action) can be correlated to the audit records (the "effect" of the action) through the `transactionId` GUID
+* if a xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] or xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`] (the latter now deprecated) is configured, they provide better traceability as the `Command` is also correlated with any published events, again through the unique `transactionId` GUID
+* if a xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuderService[`AuditerService`] or xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditService[`AuditingService`] (the latter now deprecated) is configured, they provide better audit information, since the `Command` (the 'cause' of an action) can be correlated to the audit records (the "effect" of the action) through the `transactionId` GUID
 
 As of `1.13.0`, these other uses cases are now more fully supported through the
-xref:rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] service and persistent implementations of the ``Interaction`` object, eg as provided by the (non-ASF)
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] service and persistent implementations of the ``Interaction`` object, eg as provided by the (non-ASF)
 http://github.com/isisaddons/isis-module-publishmq[Isis addons' publishmq] module.
 
 
@@ -109,13 +109,13 @@ public interface Command extends HasTransactionId {
 <16> `getResult()` - bookmark to object returned by action, if any
 <17> `getException()` - exception stack trace if action threw exception
 <18> No longer used by the framework; see instead
-xref:rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] and `Interaction#next()`.
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] and `Interaction#next()`.
 
 
 
 == Usage
 
-The typical way to indicate that an action should be treated as a command is to annotate it with the xref:rgant.adoc#_rgant-Action_command[`@Action#command()`] annotation.
+The typical way to indicate that an action should be treated as a command is to annotate it with the xref:../rgant/rgant.adoc#_rgant-Action_command[`@Action#command()`] annotation.
 
 For example:
 
@@ -132,11 +132,11 @@ public class ToDoItem ... {
 ====
 As an alternative to annotating every action with `@Action#command()`, alternatively this can be configured as the default using `isis.services.command.actions` configuration property.
 
-See xref:rgant.adoc#_rgant-Action_command[`@Action#command()`] and xref:rgcfg.adoc#_rgcfg_configuring-core[runtime configuration] for further details.
+See xref:../rgant/rgant.adoc#_rgant-Action_command[`@Action#command()`] and xref:../rgcfg/rgcfg.adoc#_rgcfg_configuring-core[runtime configuration] for further details.
 ====
 
 
-The xref:rgant.adoc#_rgant-Action_command[`@Action#command()`] annotation can also be used to specify whether the command should be performed in the background, for example:
+The xref:../rgant/rgant.adoc#_rgant-Action_command[`@Action#command()`] annotation can also be used to specify whether the command should be performed in the background, for example:
 
 [source,java]
 ----
@@ -151,7 +151,7 @@ public class ToDoItem ... {
 
 When a background command is invoked, the user is returned the command object itself (to provide a handle to the command being invoked).
 
-This requires that an implementation of xref:rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] that persists the commands (such as the (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module's `CommandService`) is configured. It also requires that a scheduler is configured to execute the background commands, see xref:rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[`BackgroundCommandService`]).
+This requires that an implementation of xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] that persists the commands (such as the (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module's `CommandService`) is configured. It also requires that a scheduler is configured to execute the background commands, see xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[`BackgroundCommandService`]).
 
 
 
@@ -186,7 +186,7 @@ public class ToDoItem ... {
 
 If run in the background, it might then notify the user (eg by email) if all work is done.
 
-This leads us onto a related point, distinguishing the current effective user vs the originating "real" user. When running in the foreground, the current user can be obtained from the xref:rgsvc.adoc#_rgsvc_api_UserService[`UserService`], using:
+This leads us onto a related point, distinguishing the current effective user vs the originating "real" user. When running in the foreground, the current user can be obtained from the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_UserService[`UserService`], using:
 
 [source,java]
 ----
@@ -209,13 +209,13 @@ String user = commandContext.getCommand().getUser();
 == Registering the Services
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
 implementation of `CommandContext` service is automatically registered and injected (it is annotated with
 `@DomainService`) so no further configuration is required.
 
 To use an alternative implementation, use
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
+xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+in the xref:../rgsvc/rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
 
 
 
@@ -223,21 +223,21 @@ in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to th
 
 == Related Services
 
-The xref:rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`] service is very similar in nature to the xref:rgsvc.adoc#_rgsvc_api_InteactionContext[`InteactionContext`], in that the
+The xref:../rgsvc/rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`] service is very similar in nature to the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_InteactionContext[`InteactionContext`], in that the
 `Command` object accessed through it is very similar to the `Interaction` object obtained from the `InteractionContext`.
 The principle distinction is that while `Command` represents the __intention__ to invoke an action or edit a property,
 the `Interaction` (and contained ``Execution``s) represents the actual execution.
 
 Most of the time a `Command` will be followed directly by its corresponding `Interaction`.  However, if the `Command`
-is annotated to run in the background (using xref:rgant.adoc#_rgant-Action_command[`@Action#commandExecuteIn()`], or
-is explicitly created through the xref:rgsvc.adoc#_rgsvc_api_BackgroundService[`BackgroundService`], then the actual
+is annotated to run in the background (using xref:../rgant/rgant.adoc#_rgant-Action_command[`@Action#commandExecuteIn()`], or
+is explicitly created through the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BackgroundService[`BackgroundService`], then the actual
 interaction/execution is deferred until some other mechanism invokes the command (eg as described
 xref:ugbtb.adoc#_ugbtb_headless-access_BackgroundCommandExecution[here]).  The persistence of background commands
-requires a configured xref:rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[`BackgroundCommandService`]) to actually
+requires a configured xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[`BackgroundCommandService`]) to actually
 persist such commands for execution.
 
 ``Command``s - even if executed in the foreground - can also be persisted by way of the
-xref:rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`].  Implementations of `CommandService` and
+xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`].  Implementations of `CommandService` and
 `BackgroundCommandService` are intended to go together, so that child ``Command``s persistent (to be executed in the
 background) can be associated with their parent ``Command``s (executed in the foreground, with the background `Command`
-created explicitly through the xref:rgsvc.adoc#_rgsvc_api_BackgroundService[`BackgroundService`]).
+created explicitly through the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BackgroundService[`BackgroundService`]).

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_ConfigurationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_ConfigurationService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_ConfigurationService.adoc
index 3beba97..e41de92 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_ConfigurationService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_ConfigurationService.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-The `ConfigurationService` allows domain objects to read the configuration properties aggregated from the various xref:rgcfg.adoc#_rgcfg_configuration-files[configuration files].
+The `ConfigurationService` allows domain objects to read the configuration properties aggregated from the various xref:../rgcfg/rgcfg.adoc#_rgcfg_configuration-files[configuration files].
 
 
 [IMPORTANT]
@@ -15,7 +15,7 @@ Only configuration properties with the prefix "application" are be exposed.
 
 [NOTE]
 ====
-The methods in this service replace similar methods (now deprecated) in xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`].
+The methods in this service replace similar methods (now deprecated) in xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`].
 ====
 
 
@@ -61,7 +61,7 @@ public class TweetService {
 
 [TIP]
 ====
-If you _do_ have a domain service that needs to access Isis properties, then an alternative is to define a xref:rgant.adoc#_rgant-PostConstruct[`@PostConstruct`] method and pass in a `Map<String,String>` of properties.
+If you _do_ have a domain service that needs to access Isis properties, then an alternative is to define a xref:../rgant/rgant.adoc#_rgant-PostConstruct[`@PostConstruct`] method and pass in a `Map<String,String>` of properties.
 This is provided all properties, not just those with the 'application' prefix.
 ====
 
@@ -79,13 +79,13 @@ The core framework provides a default implementation of this service (`o.a.i.cor
 == Registering the Service
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
 implementation of `ConfigurationService` service is automatically registered and injected (it is annotated with
 `@DomainService`) so no further configuration is required.
 
 To use an alternative implementation, use
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
+xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+in the xref:../rgsvc/rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DeepLinkService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DeepLinkService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DeepLinkService.adoc
index ab84547..25341d0 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DeepLinkService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DeepLinkService.adoc
@@ -25,13 +25,13 @@ public interface DeepLinkService {
 ----
 <1> Creates a URI that can be used to obtain a representation of the provided domain object in one of the Apache Isis viewers.
 
-The xref:ugvw.adoc#[Wicket viewer] this provides an implementation for accessing the representation through this viewer.  (For the xref:ugvro.adoc#[RestfulObjects viewer], a URL can be constructed according to the link:http://www.restfulobjects.org[Restful Objects spec] in conjunction with a `Bookmark` obtained via the xref:rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`]).
+The xref:ugvw.adoc#[Wicket viewer] this provides an implementation for accessing the representation through this viewer.  (For the xref:ugvro.adoc#[RestfulObjects viewer], a URL can be constructed according to the link:http://www.restfulobjects.org[Restful Objects spec] in conjunction with a `Bookmark` obtained via the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`]).
 
 
 
 == Usage within the framework
 
-The xref:rgsvc.adoc#_rgsvc_spi_EmailNotificationService[`EmailNotificationService`] uses this service in order to generate emails as part of xref:ugvw.adoc#_ugvw_features_user-registration[user registration].
+The xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_EmailNotificationService[`EmailNotificationService`] uses this service in order to generate emails as part of xref:ugvw.adoc#_ugvw_features_user-registration[user registration].
 
 
 
@@ -47,10 +47,10 @@ The Wicket viewer core framework provides a default implementation of this API:
 == Registering the Services
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]), _and_ that the
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]), _and_ that the
 xref:ugvw.adoc#[Wicket viewer] is being used, then an implementation of `DeepLinkService` is
 automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
 
 To use an alternative implementation, use
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
+xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+in the xref:../rgsvc/rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DomainObjectContainer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DomainObjectContainer.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DomainObjectContainer.adoc
index 177c7e7..0657cbf 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DomainObjectContainer.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DomainObjectContainer.adoc
@@ -10,7 +10,7 @@ The `DomainObjectContainer` service provides a set of general purpose functional
 
 [NOTE]
 ====
-(Almost all of) the methods in this service have been moved out into a number of more fine-grained services: xref:rgsvc.adoc#_rgsvc_api_RepositoryService[`RepositoryService`], xref:rgsvc.adoc#_rgsvc_api_MessageService[`MessageService`], xref:rgsvc.adoc#_rgsvc_api_FactoryService[`FactoryService`], xref:rgsvc.adoc#_rgsvc_api_TitleService[`TitleService`], xref:rgsvc.adoc#_rgsvc_api_ConfigurationService[`ConfigurationService`], xref:rgsvc.adoc#_rgsvc_api_UserService[`UserService`] and xref:rgsvc.adoc#_rgsvc_api_ServiceRegistry[`ServiceRegistry`].
+(Almost all of) the methods in this service have been moved out into a number of more fine-grained services: xref:../rgsvc/rgsvc.adoc#_rgsvc_api_RepositoryService[`RepositoryService`], xref:../rgsvc/rgsvc.adoc#_rgsvc_api_MessageService[`MessageService`], xref:../rgsvc/rgsvc.adoc#_rgsvc_api_FactoryService[`FactoryService`], xref:../rgsvc/rgsvc.adoc#_rgsvc_api_TitleService[`TitleService`], xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ConfigurationService[`ConfigurationService`], xref:../rgsvc/rgsvc.adoc#_rgsvc_api_UserService[`UserService`] and xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ServiceRegistry[`ServiceRegistry`].
 ====
 
 
@@ -43,7 +43,7 @@ The core framework provides a default implementation of this service (`o.a.i.cor
 == Registering the Service
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
 implementation of `DomainObjectContainer` service is automatically registered and injected (it is annotated with
 `@DomainService`) so no further configuration is required.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DomainObjectContainer_generic-repository-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DomainObjectContainer_generic-repository-api.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DomainObjectContainer_generic-repository-api.adoc
index cf35c3a..c419770 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DomainObjectContainer_generic-repository-api.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DomainObjectContainer_generic-repository-api.adoc
@@ -8,7 +8,7 @@
 
 The repository API acts as an abstraction over the JDO/DataNucleus objectstore.  You can use it during prototyping to write naive queries (find all rows, then filter using the Guava `Predicate` API, or you can use it to call JDO link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/query.html#named[named queries] using JDOQL.
 
-As an alternative, you could also use link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/jdoql_typesafe.html[JDO typesafe queries] through the xref:rgsvc.adoc#_rgsvc_api_IsisJdoSupport[`IsisJdoSupport`] service.
+As an alternative, you could also use link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/jdoql_typesafe.html[JDO typesafe queries] through the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_IsisJdoSupport[`IsisJdoSupport`] service.
 
 
 [source,java]
@@ -80,5 +80,5 @@ With respect to the other query APIs, the varargs parameters are optional, but a
 
 [TIP]
 ====
-It is also possible to query using DataNucleus' type-safe query API.  For more details, see xref:rgsvc.adoc#_rgsvc_api_IsisJdoSupport[`IsisJdoSupport`].
+It is also possible to query using DataNucleus' type-safe query API.  For more details, see xref:../rgsvc/rgsvc.adoc#_rgsvc_api_IsisJdoSupport[`IsisJdoSupport`].
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DomainObjectContainer_object-creation-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DomainObjectContainer_object-creation-api.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DomainObjectContainer_object-creation-api.adoc
index 24f6127..7aebfee 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DomainObjectContainer_object-creation-api.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DomainObjectContainer_object-creation-api.adoc
@@ -19,9 +19,9 @@ public interface DomainObjectContainer {
 }
 ----
 <1> create a new non-persisted domain entity.  Any services will be automatically injected into the service.
-<2> create a new view model, with the specified memento (as per xref:rgcms.adoc#_rgcms_classes_super_AbstractViewModel[ViewModel#viewModelMemento()].  In general it is easier to just annotate with xref:rgant.adoc#_rgant-ViewModel[`@ViewModel`] and let Apache Isis manage the memento automatically.
+<2> create a new view model, with the specified memento (as per xref:../rgcms/rgcms.adoc#_rgcms_classes_super_AbstractViewModel[ViewModel#viewModelMemento()].  In general it is easier to just annotate with xref:../rgant/rgant.adoc#_rgant-ViewModel[`@ViewModel`] and let Apache Isis manage the memento automatically.
 <3> programmatically instantiate a mixin, as annotated with
-xref:rgant.adoc#_rgant-Mixin[`@Mixin`] or xref:rgant.adoc#_rgant-DomainObject_nature[`@DomainObject#nature()`].
+xref:../rgant/rgant.adoc#_rgant-Mixin[`@Mixin`] or xref:../rgant/rgant.adoc#_rgant-DomainObject_nature[`@DomainObject#nature()`].
 
 For example:
 
@@ -38,9 +38,9 @@ Doing this will not inject any domain services, but they can be injected manuall
 
 [NOTE]
 ====
-Calling `new(...)` also this circumvents Apache Isis' xref:rgcms.adoc#_rgcms_methods_reserved_created[`created()`]
+Calling `new(...)` also this circumvents Apache Isis' xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_created[`created()`]
 callback, and in addition any default values for properties (either explicitly set by
-xref:rgcms.adoc#_rgcms_methods_prefixes_default[`default...()`] or defaulted implicitly according to Apache Isis'
+xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_default[`default...()`] or defaulted implicitly according to Apache Isis'
 own conventions) will not be called either.  If you don't intend to use these features, though, the net effect is code
 that has less coupling to Isis and is arguably easier to understand (has "less magic" happening).
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DomainObjectContainer_object-persistence-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DomainObjectContainer_object-persistence-api.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DomainObjectContainer_object-persistence-api.adoc
index edb4b5e..120a81a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DomainObjectContainer_object-persistence-api.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DomainObjectContainer_object-persistence-api.adoc
@@ -7,7 +7,7 @@
 
 
 
-The persistence API is used to persist newly created objects (as per xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-creation-api[`#newTransientInstance(...)`], above and to delete (remove) objects that are persistent.
+The persistence API is used to persist newly created objects (as per xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-creation-api[`#newTransientInstance(...)`], above and to delete (remove) objects that are persistent.
 
 Note that there is no API for updating existing objects; the framework (or rather, JDO/DataNucleus) performs object dirty tracking and so any objects that are modified in the course of a request will be automatically updated).
 
@@ -31,7 +31,7 @@ public interface DomainObjectContainer {
 }
 ----
 <1> test whether a particular domain object is persistent or not.
-<2> test whether a particular domain object is a view model or not.  Note that this includes any domain objects annotated with xref:rgant.adoc#_rgant-DomainObject_nature[`@DomainObject#nature=Nature.EXTERNAL_ENTITY)`] or xref:rgant.adoc#_rgant-DomainObject_nature[`@DomainObject#nature=Nature.INMEMORY_ENTITY`]
+<2> test whether a particular domain object is a view model or not.  Note that this includes any domain objects annotated with xref:../rgant/rgant.adoc#_rgant-DomainObject_nature[`@DomainObject#nature=Nature.EXTERNAL_ENTITY)`] or xref:../rgant/rgant.adoc#_rgant-DomainObject_nature[`@DomainObject#nature=Nature.INMEMORY_ENTITY`]
 <3> persist a transient object.  Note though that this will throw an exception if the object is already persistent; this can happen if JDO/DataNucleus's link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/orm/cascading.html[persistence-by-reachability] is in effect.  For this reason it is generally better to use `persistIfNotAlready(...)`. Also note that `persist(...)` has been deprecate.  When moving to xref:rgsvc_api_RepositoryService.adoc#_rgsvc_api_RepositoryService[`RepositoryService#persist()`] take into account that its behavior is identical to <4>, being a no-op if the object is persistent, instead of throwing an exception.
 <4> persist an object but only if know to not have been persistent.  But if the object is persistent, is a no-op
 <5> remove (ie DELETE) a persistent object.  For similar reasons to the persistence, it is generally better to use:
@@ -50,7 +50,7 @@ container.persistIfNotAlready(cust);
 
 You should be aware that by default Apache Isis queues up calls to `#persist()` and `#remove()`.  These are then executed either when the request completes (and the transaction commits), or if the queue is flushed.  This can be done either implicitly by the framework, or as the result of a direct call to `#flush()`.
 
-By default the framework itself will cause `#flush()` to be called whenever a query is executed by way of `#allMatches(Query)`, as documented xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer_generic-repository-api[above].  However, this behaviour can be disabled using the  xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.services.container.disableAutoFlush`.
+By default the framework itself will cause `#flush()` to be called whenever a query is executed by way of `#allMatches(Query)`, as documented xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer_generic-repository-api[above].  However, this behaviour can be disabled using the  xref:../rgcfg/rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.services.container.disableAutoFlush`.
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DomainObjectContainer_presentation-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DomainObjectContainer_presentation-api.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DomainObjectContainer_presentation-api.adoc
index 8feba94..a443bdc 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DomainObjectContainer_presentation-api.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DomainObjectContainer_presentation-api.adoc
@@ -7,11 +7,11 @@
 
 
 
-A responsibility of every domain object is to return a title.  This can be done declaratively using the xref:rgant.adoc#_rgant-Title[`@Title`] annotation on property/ies, or it can be done imperatively by writing a xref:rgcms.adoc#_rgcms_methods_reserved_title[`title()`] method.
+A responsibility of every domain object is to return a title.  This can be done declaratively using the xref:../rgant/rgant.adoc#_rgant-Title[`@Title`] annotation on property/ies, or it can be done imperatively by writing a xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_title[`title()`] method.
 
 It's quite common for titles to be built up of the titles of other objects.  If using building up the title using `@Title` then Apache Isis will automatically use the title of the objects referenced by the annotated properties.  We also need programmatic access to these titles if going the imperative route.
 
-Similarly, it often makes sense if xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer_messages-api[raising messages] to use the title of an object in a message rather (than a some other property of the object), because this is how end-users will be used to identifying the object.
+Similarly, it often makes sense if xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer_messages-api[raising messages] to use the title of an object in a message rather (than a some other property of the object), because this is how end-users will be used to identifying the object.
 
 The API defined by `DomainObjectContainer` is simply:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DomainObjectContainer_properties-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DomainObjectContainer_properties-api.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DomainObjectContainer_properties-api.adoc
index 52ec654..a0d1e2a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DomainObjectContainer_properties-api.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DomainObjectContainer_properties-api.adoc
@@ -8,7 +8,7 @@
 
 = Properties API
 
-The properties API allows domain objects to read the configuration properties aggregated from the various xref:rgcfg.adoc#_rgcfg_configuration-files[configuration files].
+The properties API allows domain objects to read the configuration properties aggregated from the various xref:../rgcfg/rgcfg.adoc#_rgcfg_configuration-files[configuration files].
 
 [source,java]
 ----
@@ -44,7 +44,7 @@ public class TweetService {
 
 [TIP]
 ====
-If you _do_ have a domain service that needs to access properties, then note that an alternative is to define a xref:rgant.adoc#_rgant-PostConstruct[`@PostConstruct`] method and pass in a `Map<String,String>` of properties.  The two techniques are almost identical; it's mostly a matter of taste.
+If you _do_ have a domain service that needs to access properties, then note that an alternative is to define a xref:../rgant/rgant.adoc#_rgant-PostConstruct[`@PostConstruct`] method and pass in a `Map<String,String>` of properties.  The two techniques are almost identical; it's mostly a matter of taste.
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DomainObjectContainer_services-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DomainObjectContainer_services-api.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DomainObjectContainer_services-api.adoc
index da65ece..29c2064 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DomainObjectContainer_services-api.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DomainObjectContainer_services-api.adoc
@@ -18,11 +18,11 @@ public interface DomainObjectContainer {
     ...
 }
 ----
-<1> injects services into domain object; used extensively internally by the framework (eg to inject to other services, or to entities, or integration test instances, or fixture scripts).  Service injection is done automatically if objects are created using `#newTransientInstance()`, described xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-creation-api[above]
+<1> injects services into domain object; used extensively internally by the framework (eg to inject to other services, or to entities, or integration test instances, or fixture scripts).  Service injection is done automatically if objects are created using `#newTransientInstance()`, described xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-creation-api[above]
 <2> returns the first registered service that implements the specified class
 <3> returns an `Iterable` in order to iterate over all registered services that implement the specified class
 
-The primary use case is to instantiate domain objects using a regular constructor ("new is the new new") rather than using the xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-creation-api[`#newTransientInstance()`] API, and then using the `#injectServicesInto(...)` API to set up any dependencies.
+The primary use case is to instantiate domain objects using a regular constructor ("new is the new new") rather than using the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-creation-api[`#newTransientInstance()`] API, and then using the `#injectServicesInto(...)` API to set up any dependencies.
 
 For example:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DomainObjectContainer_validation-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DomainObjectContainer_validation-api.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DomainObjectContainer_validation-api.adoc
index 96d4fda..40aedab 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DomainObjectContainer_validation-api.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DomainObjectContainer_validation-api.adoc
@@ -7,7 +7,7 @@
 
 The intent of this API is to provide a mechanism where an object can programmatically check the state any class
 invariants.  Specifically, this means the validating the current state of all properties, as well as any object-level
-validation defined by xref:rgcms.adoc#_rgcms_methods_reserved_validate[`validate()`].
+validation defined by xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_validate[`validate()`].
 
 [WARNING]
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_EmailService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_EmailService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_EmailService.adoc
index 8d9327b..1f44047 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_EmailService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_EmailService.adoc
@@ -47,7 +47,7 @@ To use this service the following properties must be configured:
 * `isis.service.email.sender.address`
 * `isis.service.email.sender.password`
 
-and these properties may optionally be configured (each has a default to use gmail, documented xref:rgcfg.adoc#_rgcfg_configuring-core[here]):
+and these properties may optionally be configured (each has a default to use gmail, documented xref:../rgcfg/rgcfg.adoc#_rgcfg_configuring-core[here]):
 
 * `isis.service.email.sender.hostname`
 * `isis.service.email.port`
@@ -112,11 +112,11 @@ To ensure that your alternative implementation takes the place of the default im
 
 == Registering the Services
 
-Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the `AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core implementation of `EmailService` service is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
+Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the `AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core implementation of `EmailService` service is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
 
-To use an alternative implementation, use xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
+To use an alternative implementation, use xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained in the xref:../rgsvc/rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
 
 
 == Related Services
 
-The email service is used by the xref:rgsvc.adoc#_rgsvc_spi_EmailNotificationService[`EmailNotificationService`] which is, in turn, used by xref:rgsvc.adoc#_rgsvc_spi_UserRegistrationService[`UserRegistrationService`].
\ No newline at end of file
+The email service is used by the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_EmailNotificationService[`EmailNotificationService`] which is, in turn, used by xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UserRegistrationService[`UserRegistrationService`].
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_EventBusService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_EventBusService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_EventBusService.adoc
index 36e0cb8..2d8c3de 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_EventBusService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_EventBusService.adoc
@@ -8,7 +8,7 @@
 
 The `EventBusService` allows domain objects to emit events to subscribing domain services using an in-memory event bus.
 
-The primary user of the service is the framework itself, which automatically emit events for xref:rgant.adoc#_rgant-Action_domainEvent[actions], xref:rgant.adoc#_rgant-Property_domainEvent[properties] and xref:rgant.adoc#_rgant-Collection_domainEvent[collections].  Multiple events are generated:
+The primary user of the service is the framework itself, which automatically emit events for xref:../rgant/rgant.adoc#_rgant-Action_domainEvent[actions], xref:../rgant/rgant.adoc#_rgant-Property_domainEvent[properties] and xref:../rgant/rgant.adoc#_rgant-Collection_domainEvent[collections].  Multiple events are generated:
 
 * when an object member is to be viewed, an event is fired; subscribers can veto (meaning that the member is hidden)
 * when an object member is to be enabled, the same event instance is fired; subscribers can veto (meaning that the member is disabled, ie cannot be edited/invoked)
@@ -16,7 +16,7 @@ The primary user of the service is the framework itself, which automatically emi
 * when an object member is about to be changed, then the same event instance is fired; subscribers can perform pre-execution operations
 * when an object member has been changed, then the same event instance is fired; subscribers can perform post-execution operations
 
-If a subscriber throws an exception in the first three steps, then the interaction is vetoed. If a subscriber throws an exception in the last two steps, then the transaction is aborted.  For more on this topic, see xref:rgant.adoc#_rgant-Action_domainEvent[`@Action#domainEvent()`], xref:rgant.adoc#_rgant-Property_domainEvent[`@Property#domainEvent()`] and xref:rgant.adoc#_rgant-Collection_domainEvent[`@Collection#domainEvent()`].
+If a subscriber throws an exception in the first three steps, then the interaction is vetoed. If a subscriber throws an exception in the last two steps, then the transaction is aborted.  For more on this topic, see xref:../rgant/rgant.adoc#_rgant-Action_domainEvent[`@Action#domainEvent()`], xref:../rgant/rgant.adoc#_rgant-Property_domainEvent[`@Property#domainEvent()`] and xref:../rgant/rgant.adoc#_rgant-Collection_domainEvent[`@Collection#domainEvent()`].
 
 It is also possible for domain objects to programmatically generate domain events.  However the events are published, the primary use case is to decoupling interactions from one module/package/namespace and another.
 
@@ -41,7 +41,7 @@ public abstract class EventBusService {
 }
 ----
 <1> posts the event onto event bus
-<2> allows domain services to register themselves.  This should be done in their xref:rgant.adoc#_rgant-PostConstruct[`@PostConstruct`] initialization method (for both singleton and xref:rgant.adoc#_rgant-RequestScoped[`@RequestScoped`] domain services.
+<2> allows domain services to register themselves.  This should be done in their xref:../rgant/rgant.adoc#_rgant-PostConstruct[`@PostConstruct`] initialization method (for both singleton and xref:../rgant/rgant.adoc#_rgant-RequestScoped[`@RequestScoped`] domain services.
 <3> exists for symmetry, but need never be called (it is in fact deliberately a no-op).
 
 Isis provides a default implementation of the service, `o.a.i.objectstore.jdo.datanucleus.service.eventbus.EventBusServiceJdo`.
@@ -52,7 +52,7 @@ Isis provides a default implementation of the service, `o.a.i.objectstore.jdo.da
 
 == Registering Subscribers
 
-The `register()` method should be called in the xref:rgant.adoc#_rgant-PostConstruct[`@PostConstruct`] lifecycle method.  It is valid and probably the least confusing to readers to also "unregister" in the xref:rgant.adoc#_rgant-PreDestroy[`@PreDestroy`] lifecycle method (though as noted xref:rgsvc.adoc#__rgsvc_api_EventBusService_api-and-implementation[above], unregistering is actually a no-op).
+The `register()` method should be called in the xref:../rgant/rgant.adoc#_rgant-PostConstruct[`@PostConstruct`] lifecycle method.  It is valid and probably the least confusing to readers to also "unregister" in the xref:../rgant/rgant.adoc#_rgant-PreDestroy[`@PreDestroy`] lifecycle method (though as noted xref:../rgsvc/rgsvc.adoc#__rgsvc_api_EventBusService_api-and-implementation[above], unregistering is actually a no-op).
 
 For example:
 
@@ -78,20 +78,20 @@ public class MySubscribingDomainService {
 <2> It's important that subscribers register before any domain services that might emit events on the event bus service.
 For example, the (non-ASF) http://github.com/isisaddons/isis-module-security[Isis addons' security] module provides a
 domain service that automatically seeds certain domain entities; these will generate
-xref:rgcms.adoc#_rgcms_classes_lifecycleevent[lifecycle events] and so any subscribers must be registered before such seed
-services.  The easiest way to do this is to use the xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] attribute.
-<3> register with the event bus service during xref:rgant.adoc#_rgant-PostConstruct[`@PostConstruct`]
+xref:../rgcms/rgcms.adoc#_rgcms_classes_lifecycleevent[lifecycle events] and so any subscribers must be registered before such seed
+services.  The easiest way to do this is to use the xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] attribute.
+<3> register with the event bus service during xref:../rgant/rgant.adoc#_rgant-PostConstruct[`@PostConstruct`]
     initialization
 <4> corresponding deregister when shutting down
 
-This works for both singleton (application-scoped) and also xref:rgant.adoc#_rgant-RequestScoped[`@RequestScoped`] domain services.
+This works for both singleton (application-scoped) and also xref:../rgant/rgant.adoc#_rgant-RequestScoped[`@RequestScoped`] domain services.
 
 
 [TIP]
 ====
-The xref:rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[`AbstractSubscriber`] class automatically performs this
+The xref:../rgcms/rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[`AbstractSubscriber`] class automatically performs this
 registration.  As a convenience, it is also annotated with the
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] attribute.
+xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] attribute.
 ====
 
 
@@ -149,7 +149,7 @@ public class LibraryMember {
     ...
 }
 ----
-<1> `LibraryMemberLeaveEvent` is a subclass of `o.a.i.applib.eventbus.ActionDomainEvent`.  The topic of subclassing is discussed in more detail xref:rgsvc.adoc#__rgsvc_api_EventBusService_event-hierarchy[below].
+<1> `LibraryMemberLeaveEvent` is a subclass of `o.a.i.applib.eventbus.ActionDomainEvent`.  The topic of subclassing is discussed in more detail xref:../rgsvc/rgsvc.adoc#__rgsvc_api_EventBusService_event-hierarchy[below].
 
 Meanwhile, in the `BookRepository` domain service, we subscribe to the event and act upon it.  For example:
 
@@ -282,13 +282,13 @@ public class LibraryMember {
 ----
 <1> `LibraryMember.LeaveEvent` could be _any_ class, not just a subclass of `o.a.i.applib.event.ActionDomainEvent`.
 
-In practice we suspect there will be few cases where the programmatic approach is required rather than the declarative approach afforded by xref:rgant.adoc#_rgant-Action_domainEvent[`@Action#domainEvent()`] et al.
+In practice we suspect there will be few cases where the programmatic approach is required rather than the declarative approach afforded by xref:../rgant/rgant.adoc#_rgant-Action_domainEvent[`@Action#domainEvent()`] et al.
 
 
 
 == Using `WrapperFactory`
 
-An alternative way to cause events to be posted is through the xref:rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`].  This is useful when you wish to enforce a (lack-of-) trust boundary between the caller and the callee.
+An alternative way to cause events to be posted is through the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`].  This is useful when you wish to enforce a (lack-of-) trust boundary between the caller and the callee.
 
 For example, suppose that `Customer#placeOrder(...)` emits a `PlaceOrderEvent`, which is subscribed to by a `ReserveStockSubscriber`.  This subscriber in turn calls `StockManagementService#reserveStock(...)`.  Any business rules on `#reserveStock(...)` should be enforced.
 
@@ -315,12 +315,12 @@ public class ReserveStockSubscriber {
 
 == Implementation SPI
 
-The implementation of `EventBusService` provided by Apache Isis will by default use link:https://code.google.com/p/guava-libraries/[Guava]'s https://code.google.com/p/guava-libraries/wiki/EventBusExplained[`EventBus`] as the underlying in-memory event bus.  Alternatively the link:http://www.axonframework.org/[AxonFramework]'s link:http://www.axonframework.org/docs/2.4/single.html#d5e1489[SimpleEventBus] can be used.  Which is used is specified through configuration property (described xref:rgsvc.adoc#__rgsvc_api_EventBusService_Configuration[below]).
+The implementation of `EventBusService` provided by Apache Isis will by default use link:https://code.google.com/p/guava-libraries/[Guava]'s https://code.google.com/p/guava-libraries/wiki/EventBusExplained[`EventBus`] as the underlying in-memory event bus.  Alternatively the link:http://www.axonframework.org/[AxonFramework]'s link:http://www.axonframework.org/docs/2.4/single.html#d5e1489[SimpleEventBus] can be used.  Which is used is specified through configuration property (described xref:../rgsvc/rgsvc.adoc#__rgsvc_api_EventBusService_Configuration[below]).
 
 [NOTE]
 .Guava vs Axon, which to use?
 ====
-Guava actually queues up events; they are not guaranteed to be dispatched immediately.  This generally is not problem, but can be for cases where the subscriber may in turn want to post its own events (using xref:rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`]).
+Guava actually queues up events; they are not guaranteed to be dispatched immediately.  This generally is not problem, but can be for cases where the subscriber may in turn want to post its own events (using xref:../rgsvc/rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`]).
 
 The Axon `SimpleEventBus`-based implementation on the other hand is fully synchronous; events are dispatched as soon as they are posted.  This works well in all scenarios (that we have tested).
 ====
@@ -348,7 +348,7 @@ If you do provide your own implementation of this SPI, be aware that your subscr
 
 The implementation of `EventBusService` provided by Apache Isis will by default use link:https://code.google.com/p/guava-libraries/[Guava]'s https://code.google.com/p/guava-libraries/wiki/EventBusExplained[`EventBus`] as the underlying in-memory event bus.  Alternatively the link:http://www.axonframework.org/[AxonFramework]'s link:http://www.axonframework.org/docs/2.4/single.html#d5e1489[SimpleEventBus] can be used.
 
-To specify which, add the xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.services.eventbus.implementation`:
+To specify which, add the xref:../rgcfg/rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.services.eventbus.implementation`:
 
 [source,ini]
 ----
@@ -387,13 +387,13 @@ Late registration refers to the idea that a domain service can register itself w
 == Registering the Services
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
 implementation of `EventBusService` service is automatically registered and injected (it is annotated with
 `@DomainService`) so no further configuration is required.
 
 To use an alternative implementation, use
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
+xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+in the xref:../rgsvc/rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
 
 
 
@@ -402,4 +402,4 @@ in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to th
 
 The `EventBusService` is intended for fine-grained publish/subscribe for object-to-object interactions within an Apache Isis domain object model. The event propagation is strictly in-memory, and there are no restrictions on the object acting as the event (it need not be serializable, for example).
 
-The xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`] meanwhile is intended for coarse-grained publish/subscribe for system-to-system interactions, from Apache Isis to some other system. Here the only events published are those that action invocations (for actions annotated with xref:rgant.adoc#_rgant-Action_publishing[`@Action#publishing()`]) and of changed objects (for objects annotated with xref:rgant.adoc#_rgant-DomainObject_publishing[`@DomainObject#publishing()`]).
\ No newline at end of file
+The xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`] meanwhile is intended for coarse-grained publish/subscribe for system-to-system interactions, from Apache Isis to some other system. Here the only events published are those that action invocations (for actions annotated with xref:../rgant/rgant.adoc#_rgant-Action_publishing[`@Action#publishing()`]) and of changed objects (for objects annotated with xref:../rgant/rgant.adoc#_rgant-DomainObject_publishing[`@DomainObject#publishing()`]).
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_FactoryService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_FactoryService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_FactoryService.adoc
index d11c11b..e7563e0 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_FactoryService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_FactoryService.adoc
@@ -9,7 +9,7 @@ The `FactoryService` collects together methods for instantiating domain objects.
 
 [NOTE]
 ====
-The methods in this service replace similar methods (now deprecated) in xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`].
+The methods in this service replace similar methods (now deprecated) in xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`].
 ====
 
 
@@ -25,16 +25,16 @@ public interface FactoryService {
 }
 ----
 <1> create a new non-persisted domain entity.  Any services will be automatically injected into the service.
-<2> programmatically instantiate a mixin, as annotated with xref:rgant.adoc#_rgant-Mixin[`@Mixin`] or xref:rgant.adoc#_rgant-DomainObject_nature[`@DomainObject#nature()`].
+<2> programmatically instantiate a mixin, as annotated with xref:../rgant/rgant.adoc#_rgant-Mixin[`@Mixin`] or xref:../rgant/rgant.adoc#_rgant-DomainObject_nature[`@DomainObject#nature()`].
 
 
 The object is created in memory, but is not persisted.  The benefits of using this method (instead of simply using the Java `new` keyword) are:
 
-* any services will be injected into the object immediately (otherwise they will not be injected until the frameworkbecomes aware of the object, typically when it is persisted through the xref:rgsvc.adoc#_rgsvc_api_RepositoryService[`RepositoryService`]
+* any services will be injected into the object immediately (otherwise they will not be injected until the frameworkbecomes aware of the object, typically when it is persisted through the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_RepositoryService[`RepositoryService`]
 
 * the default value for any properties (usually as specified by `defaultXxx()` supporting methods) will not be set and the `created()` callback will be called.
 
-The corollary is: if your code never uses `defaultXxx()` or the `created()` callback, then you can just `new` up the object.  The xref:rgsvc.adoc#_rgsvc_api_ServiceRegistry[`ServiceRegistry`] service can be used to inject services into the domain object.
+The corollary is: if your code never uses `defaultXxx()` or the `created()` callback, then you can just `new` up the object.  The xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ServiceRegistry[`ServiceRegistry`] service can be used to inject services into the domain object.
 
 
 
@@ -61,19 +61,19 @@ The core framework provides a default implementation of this service (`o.a.i.cor
 == Registering the Service
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
 implementation of `FactoryService` service is automatically registered and injected (it is annotated with
 `@DomainService`) so no further configuration is required.
 
 To use an alternative implementation, use
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
+xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+in the xref:../rgsvc/rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
 
 
 == Related Services
 
-The xref:rgsvc.adoc#_rgsvc_api_RepositoryService[`RepositoryService`] is often used in conjunction with the `FactoryService`, to persist domain objects after they have been instantiated and populated.
+The xref:../rgsvc/rgsvc.adoc#_rgsvc_api_RepositoryService[`RepositoryService`] is often used in conjunction with the `FactoryService`, to persist domain objects after they have been instantiated and populated.
 
 An alternative to using the factory service is to simply instantiate the object ("new is the new new") and then use the
-xref:rgsvc.adoc#_rgsvc_api_ServiceRegistry[`ServiceRegistry`] service to inject other domain services into the
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ServiceRegistry[`ServiceRegistry`] service to inject other domain services into the
 instantiated object.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_FixtureScriptsDefault.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_FixtureScriptsDefault.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_FixtureScriptsDefault.adoc
index a81db56..7e45125 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_FixtureScriptsDefault.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_FixtureScriptsDefault.adoc
@@ -8,13 +8,13 @@
 
 The `FixtureScriptsDefault` service provides the ability to execute xref:ugtst.adoc#_ugtst_fixture-scripts_api-and-usage[fixture scripts] .
 
-The service extends from the xref:rgcms.adoc#_rgcms_classes_super_FixtureScripts[`FixtureScripts`], and is only instantiated by the framework if there no custom implementation of `FixtureScripts` has been otherwise provided; in other words it is a fallback.
+The service extends from the xref:../rgcms/rgcms.adoc#_rgcms_classes_super_FixtureScripts[`FixtureScripts`], and is only instantiated by the framework if there no custom implementation of `FixtureScripts` has been otherwise provided; in other words it is a fallback.
 
-If this service is instantiated (as a fallback) then it uses the xref:rgsvc.adoc#_rgsvc_spi_FixtureScriptsSpecificationProvider[`FixtureScriptsSpecificationProvider`] to obtain a `FixtureScriptsSpecification`.  This configures this service, telling it which package to search for `FixtureScript` classes, how to execute those classes, and hints that influence the UI.
+If this service is instantiated (as a fallback) then it uses the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_FixtureScriptsSpecificationProvider[`FixtureScriptsSpecificationProvider`] to obtain a `FixtureScriptsSpecification`.  This configures this service, telling it which package to search for `FixtureScript` classes, how to execute those classes, and hints that influence the UI.
 
 [TIP]
 ====
-We recommend using xref:rgsvc.adoc#_rgsvc_spi_FixtureScriptsSpecificationProvider[`FixtureScriptsSpecificationProvider`] rather than subclassing xref:rgcms.adoc#_rgcms_classes_super_FixtureScripts[`FixtureScripts`].
+We recommend using xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_FixtureScriptsSpecificationProvider[`FixtureScriptsSpecificationProvider`] rather than subclassing xref:../rgcms/rgcms.adoc#_rgcms_classes_super_FixtureScripts[`FixtureScripts`].
 ====
 
 
@@ -33,18 +33,18 @@ public class FixtureScriptsDefault ... {
 }
 ----
 
-... in other words the same as xref:rgcms.adoc#_rgcms_classes_super_FixtureScripts[`FixtureScripts`] superclass that it inherits from.
+... in other words the same as xref:../rgcms/rgcms.adoc#_rgcms_classes_super_FixtureScripts[`FixtureScripts`] superclass that it inherits from.
 
 
 == Configuration
 
 As noted in the introduction, this service is only instantiated if there is no other implementation of `FixtureScripts` available on the classpath.
 
-If an instance of `FixtureScriptsSpecificationProvider` is available on the classpath, then the service will be visible in the UI (assuming xref:rgcfg.adoc#_rgcfg_deployment-types[prototype mode]).  Otherwise the service will be available only to be injected and invoked programmatically.
+If an instance of `FixtureScriptsSpecificationProvider` is available on the classpath, then the service will be visible in the UI (assuming xref:../rgcfg/rgcfg.adoc#_rgcfg_deployment-types[prototype mode]).  Otherwise the service will be available only to be injected and invoked programmatically.
 
 
 
 
 == Related Services
 
-The service interacts with xref:rgsvc.adoc#_rgsvc_spi_FixtureScriptsSpecificationProvider[`FixtureScriptsSpecificationProvider`].
+The service interacts with xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_FixtureScriptsSpecificationProvider[`FixtureScriptsSpecificationProvider`].

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_GuiceBeanProvider.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_GuiceBeanProvider.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_GuiceBeanProvider.adoc
index 44cd0dd..5a39ce3 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_GuiceBeanProvider.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_GuiceBeanProvider.adoc
@@ -7,7 +7,7 @@
 
 The `GuiceBeanProvider` domain service acts as a bridge between Apache Isis' xref:ugvw.adoc#[Wicket viewer] internal bootstrapping using link:https://github.com/google/guice[Google Guice].
 
-This service operates at a very low-level, and you are unlikely to have a need for it.  It is used internally by the framework, in the default implementation of the xref:rgsvc.adoc#_rgsvc_api_DeepLinkService[`DeepLinkService`].
+This service operates at a very low-level, and you are unlikely to have a need for it.  It is used internally by the framework, in the default implementation of the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DeepLinkService[`DeepLinkService`].
 
 [NOTE]
 ====
@@ -80,12 +80,12 @@ should return "ToDo App".
 == Registering the Services
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]), _and_ that the
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]), _and_ that the
 xref:ugvw.adoc#[Wicket viewer] is being used, then an implementation of `GuiceBeanProvider` is
 automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
 
 To use an alternative implementation, use
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
+xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+in the xref:../rgsvc/rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_HomePageProviderService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_HomePageProviderService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_HomePageProviderService.adoc
index ef3d064..5ad3845 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_HomePageProviderService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_HomePageProviderService.adoc
@@ -7,10 +7,10 @@
 
 
 This service simply provides access to the home page object (if any) that is returned from the domain service
-action annotated with xref:rgant.adoc#_rgant-HomePage[`@HomePage`].
+action annotated with xref:../rgant/rgant.adoc#_rgant-HomePage[`@HomePage`].
 
 It is originally introduced to support the default implementation of
-xref:rgsvc.adoc#_rgsvc_spi_RoutingService[`RoutingService`], but was factored out to support alternative implementations
+xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_RoutingService[`RoutingService`], but was factored out to support alternative implementations
 of that service (and may be useful for other use cases).
 
 
@@ -34,7 +34,7 @@ The default implementation is provided by `o.a.i.core.runtime.services.homepage.
 == Registering the Service
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
 implementation of `HomePageProviderService` is automatically registered (it is annotated with `@DomainService`) so no further
 configuration is required.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_InteractionContext.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_InteractionContext.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_InteractionContext.adoc
index e0acb30..503640b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_InteractionContext.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_InteractionContext.adoc
@@ -10,12 +10,12 @@ The `InteractionContext` is a request-scoped domain service that is used to obta
 `Interaction`.
 
 An `Interaction` generally consists of a single top-level `Execution`, either to invoke an action or to edit a
-property.  If that top-level action or property uses xref:rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`] to
+property.  If that top-level action or property uses xref:../rgsvc/rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`] to
 invoke child actions/properties, then those sub-executions are captured as a call-graph.  The `Execution` is thus a
 graph structure.
 
 If a bulk action is performed (as per an action annotated using
-xref:rgant.adoc#_rgant-Action_invokeOn[`@Action#invokeOn()`]), then this will result in multiple ``Interaction``s, one
+xref:../rgant/rgant.adoc#_rgant-Action_invokeOn[`@Action#invokeOn()`]), then this will result in multiple ``Interaction``s, one
 per selected object (not one `Interaction` with multiple top-level ``Execution``s).
 
 
@@ -26,10 +26,10 @@ http://github.com/isisaddons/isis-module-publishmq[Isis addons' publishmq] modul
 * they enable profiling of the running application (which actions are invoked then most often, what is their response
 time)
 
-* if auditing is configured (using either xref:rgsvc.adoc#_rgsvc_spi_AuditingService[auditing] or
-xref:rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditerService`]), they provide better audit information, since the
+* if auditing is configured (using either xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditingService[auditing] or
+xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditerService`]), they provide better audit information, since the
 `Interaction.Execution` captures the 'cause' of an interaction and can be correlated to the audit records (the "effect"
-of the interaction) by way of the xref:rgcms.adoc#_rgcms_classes_mixins_HasTransactionId[`transactionId`]
+of the interaction) by way of the xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins_HasTransactionId[`transactionId`]
 
 
 
@@ -75,11 +75,11 @@ public class Interaction {
     public int next(final String sequenceId);       // <5>
 }
 ----
-<1> The unique identifier of this interaction.  This will be the same value as held in `Command` (obtainable from xref:rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`]).
+<1> The unique identifier of this interaction.  This will be the same value as held in `Command` (obtainable from xref:../rgsvc/rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`]).
 <2> The member `Execution` (action invocation or property edit) that preceded the current one.
 <3> The current execution.
 <4> * Returns a (list of) execution}s in the order that they were pushed.  Generally there will be just one entry in this list, but additional entries may arise from the use of mixins/contributions when re-rendering a modified object.
-<5> Generates numbers in a named sequence.  Used by the framework both to number successive interaction ``Execution``s and for events published by the xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`].
+<5> Generates numbers in a named sequence.  Used by the framework both to number successive interaction ``Execution``s and for events published by the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`].
 
 This class is concrete (is also the implementation).
 
@@ -88,7 +88,7 @@ This class is concrete (is also the implementation).
 
 The `Interaction.Execution` (static nested) class represents an action invocation/property edit as a node in a
 call-stack execution graph.  Sub-executions can be performed using the
-xref:rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`].
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`].
 
 It has the following public API:
 
@@ -124,12 +124,12 @@ public abstract class Execution {
 <5> A human-friendly description of the class of the target object, and of the name of the action invoked/property
 edited on the target object.
 <6> The parent action/property that invoked this action/property edit (if any), and any actions/property edits made in
-turn via the xref:rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`].
-<7> The domain event fired via the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] representing the
+turn via the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`].
+<7> The domain event fired via the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] representing the
 execution of this action invocation/property edit.
 <8> The date/time at which this execution started/completed.
 <9> The object returned by the action invocation/property edit, or the exception thrown.  For `void` methods and for actions returning collections, the value will be `null`.
-<10> A DTO (instance of the xref:rgcms.adoc#_rgcms_schema_ixn["ixn" schema]) being a serializable representation of this action invocation/property edit.
+<10> A DTO (instance of the xref:../rgcms/rgcms.adoc#_rgcms_schema_ixn["ixn" schema]) being a serializable representation of this action invocation/property edit.
 
 
 
@@ -162,27 +162,27 @@ public class PropertyEdit extends Execution {
 
 Typically domain objects will have little need to interact with the `InteractionContext` and `Interaction` directly.
 The services are used within the framework however, primarily to support the
-xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] SPI, and to emit domain events over the
-xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`].
+xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] SPI, and to emit domain events over the
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`].
 
 
 
 == Registering the Service
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' default
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' default
 implementation of `InteractionContext` class is automatically registered (it is annotated with `@DomainService`)
 so no further configuration is required.
 
 The framework also takes responsibility for instantiating the `Interaction`, using the
-xref:rgsvc.adoc#_rgsvc_api_FactoryService[`FactoryService`].
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_FactoryService[`FactoryService`].
 
 [NOTE]
 ====
-Unlike the similar xref:rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`] (discussed
-xref:rgsvc.adoc#__rgsvc_api_InteractionContext_Related-Classes[below]) there is no domain service to different
+Unlike the similar xref:../rgsvc/rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`] (discussed
+xref:../rgsvc/rgsvc.adoc#__rgsvc_api_InteractionContext_Related-Classes[below]) there is no domain service to different
 implementations of `Interaction` to be used.  If this were to be needed, then a custom implementation of
- xref:rgsvc.adoc#_rgsvc_api_FactoryService[`FactoryService`] could always used).
+ xref:../rgsvc/rgsvc.adoc#_rgsvc_api_FactoryService[`FactoryService`] could always used).
 ====
 
 
@@ -191,14 +191,14 @@ implementations of `Interaction` to be used.  If this were to be needed, then a
 [[__rgsvc_api_InteractionContext_Related-Classes]]
 == Related Classes
 
-This service is very similar in nature to xref:rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`], in that the
+This service is very similar in nature to xref:../rgsvc/rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`], in that the
 `Interaction` object accessed through it is very similar to the `Command` object obtained from the `CommandContext`.
 The principle distinction is that while `Command` represents the __intention__ to invoke an action or edit a property,
 the `Interaction` (and contained ``Execution``s) represents the actual execution.
 
 Most of the time a `Command` will be followed directly by its corresponding `Interaction`.  However, if the `Command`
-is annotated to run in the background (using xref:rgant.adoc#_rgant-Action_command[`@Action#commandExecuteIn()`], or
-is explicitly created through the xref:rgsvc.adoc#_rgsvc_api_BackgroundService[`BackgroundService`], then the actual
+is annotated to run in the background (using xref:../rgant/rgant.adoc#_rgant-Action_command[`@Action#commandExecuteIn()`], or
+is explicitly created through the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BackgroundService[`BackgroundService`], then the actual
 interaction/execution is deferred until some other mechanism invokes the command (eg as described
 xref:ugbtb.adoc#_ugbtb_headless-access_BackgroundCommandExecution[here]).
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_IsisJdoSupport.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_IsisJdoSupport.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_IsisJdoSupport.adoc
index 7ba695c..32e2a48 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_IsisJdoSupport.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_IsisJdoSupport.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-The `IsisJdoSupport` service provides a number of general purpose methods for working with the JDO/DataNucleus objectstore.  In general these act at a lower-level of abstraction than the APIs normally used (specifically, those of xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`]), but nevertheless deal with some of the most common use cases.  For service also provides access to the underlying JDO `PersistenceManager` for full control.
+The `IsisJdoSupport` service provides a number of general purpose methods for working with the JDO/DataNucleus objectstore.  In general these act at a lower-level of abstraction than the APIs normally used (specifically, those of xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`]), but nevertheless deal with some of the most common use cases.  For service also provides access to the underlying JDO `PersistenceManager` for full control.
 
 The following sections discuss the functionality provided by the service, broken out into categories.
 
@@ -50,7 +50,7 @@ The returned value is the number of rows updated.
 
 [TIP]
 ====
-As an alternative, consider using DataNucleus' link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/jdoql_typesafe.html[type-safe JDO query API], discussed xref:rgsvc.adoc#__rgsvc_api_IsisJdoSupport_type-safe-query-api[below].
+As an alternative, consider using DataNucleus' link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/jdoql_typesafe.html[type-safe JDO query API], discussed xref:../rgsvc/rgsvc.adoc#__rgsvc_api_IsisJdoSupport_type-safe-query-api[below].
 ====
 
 
@@ -61,7 +61,7 @@ As an alternative, consider using DataNucleus' link:http://www.datanucleus.org/p
 
 DataNucleus provides an link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/jdoql_typesafe.html[extension to JDO],  so that JDOQL queries can be built up and executed using a set of type-safe classes.
 
-The types in question for type safe queries are not the domain entities, but rather are companion "Q..." query classes.  These classes are generated dynamically by an link:https://www.jcp.org/en/jsr/detail?id=269[annotation processor] as a side-effect of compilation, one "Q..." class for each of the xref:rgant.adoc#_rgant-PersistenceCapable[`@PersistenceCapable`] domain entity in your application.  For example, a `ToDoItem` domain entity will give rise to a `QToDoItem` query class.  These "Q..." classes mirror the structure of domain entity, but expose properties that allow predicates to be built up for querying instances, as well as other functions in support of order by. group by and other clauses.
+The types in question for type safe queries are not the domain entities, but rather are companion "Q..." query classes.  These classes are generated dynamically by an link:https://www.jcp.org/en/jsr/detail?id=269[annotation processor] as a side-effect of compilation, one "Q..." class for each of the xref:../rgant/rgant.adoc#_rgant-PersistenceCapable[`@PersistenceCapable`] domain entity in your application.  For example, a `ToDoItem` domain entity will give rise to a `QToDoItem` query class.  These "Q..." classes mirror the structure of domain entity, but expose properties that allow predicates to be built up for querying instances, as well as other functions in support of order by. group by and other clauses.
 
 [NOTE]
 ====
@@ -108,7 +108,7 @@ public List<ToDoItem> findByAtPathAndCategory(final String atPath, final Categor
 
 [NOTE]
 ====
-You can find the full example of the JDOQL equivalent in the xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer_generic-repository-api[`DomainObjectContainer`]
+You can find the full example of the JDOQL equivalent in the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer_generic-repository-api[`DomainObjectContainer`]
 ====
 
 
@@ -132,7 +132,7 @@ private static <T> List<T> executeListAndClose(final TypesafeQuery<T> query) {
 [[__rgsvc_api_IsisJdoSupport_fixture-support]]
 == Fixture support
 
-When writing xref:ugtst.adoc#_ugtst_integ-test-support[integration tests] you'll usually need to tear down some/all mutable transactional data before each test.  One way to do that is to use the `executeUpdate(...)` method described xref:rgsvc.adoc#__rgsvc_api_IsisJdoSupport_executing-sql[above].
+When writing xref:ugtst.adoc#_ugtst_integ-test-support[integration tests] you'll usually need to tear down some/all mutable transactional data before each test.  One way to do that is to use the `executeUpdate(...)` method described xref:../rgsvc/rgsvc.adoc#__rgsvc_api_IsisJdoSupport_executing-sql[above].
 
 Alternatively, the `deleteAll(...)` method will let your test delete all instances of a class without resorting to SQL:
 
@@ -267,10 +267,10 @@ public List<Order> findOrders(...) {
 == Registering the Services
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
 implementation of `IsisJdoSupport` service is automatically registered and injected (it is annotated with
 `@DomainService`) so no further configuration is required.
 
 To use an alternative implementation, use
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
+xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+in the xref:../rgsvc/rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_JaxbService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_JaxbService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_JaxbService.adoc
index 725f7ec..9e99ef3 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_JaxbService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_JaxbService.adoc
@@ -39,7 +39,7 @@ public interface JaxbService {
 
 With respect to the `IsisSchemas` enum: a JAXB-annotated domain object will live in its own XSD namespace and may
 reference multiple other XSD schemas.  In particular, many JAXB domain objects will reference the
-xref:rgcms.adoc#_rgcms_schema[common Isis schemas] (for example the `OidDto` class that represents a reference to
+xref:../rgcms/rgcms.adoc#_rgcms_schema[common Isis schemas] (for example the `OidDto` class that represents a reference to
 a persistent entity).  The enum indicates whether these schemas should be included or excluded from the map.
 
 Isis provides a default implementation of the service, `o.a.i.schema.services.jaxb.JaxbServiceDefault`.
@@ -49,20 +49,20 @@ Isis provides a default implementation of the service, `o.a.i.schema.services.ja
 == Usage within the framework
 
 This service is provided as a convenience for applications, but is also used internally by the framework to
-xref:rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`]-annotated
+xref:../rgant/rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`]-annotated
 xref:ugbtb.adoc#_ugbtb_view-models[view models].  The functionality to download XML and XSD schemas is also
-exposed in the UI through mixins to xref:rgcms.adoc#_rgcms_classes_mixins_Dto[`Dto`] interface.
+exposed in the UI through mixins to xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins_Dto[`Dto`] interface.
 
 
 
 == Registering the Service
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
 implementation of `JaxbService` service is automatically registered and injected (it is annotated with `@DomainService`)
 so no further configuration is required.
 
 To use an alternative implementation, use
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
+xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+in the xref:../rgsvc/rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
 

[33/58] [abbrv] isis git commit: names and descriptions

[da...@apache.org]

names and descriptions


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/4a5e96c8
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/4a5e96c8
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/4a5e96c8

Branch: refs/heads/wip
Commit: 4a5e96c8e794f8f570bb3c5a1cbd7a38cb711145
Parents: 85b1e70
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Mon Apr 17 17:56:54 2017 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Thu Apr 20 09:09:30 2017 +0100

----------------------------------------------------------------------
 .../_ugfun_ui-hints_names-and-descriptions.adoc | 48 ++++++++++++--------
 1 file changed, 30 insertions(+), 18 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/4a5e96c8/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_names-and-descriptions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_names-and-descriptions.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_names-and-descriptions.adoc
index 769ee79..dde8ed0 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_names-and-descriptions.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_names-and-descriptions.adoc
@@ -4,37 +4,49 @@
 :_basedir: ../../
 :_imagesdir: images/
 
-NOTE: FIXME
 
+The name of classes and class members are usually inferred from the Java source code directly.
+For example, an action method called `placeOrder` will be rendered as "Place Order", and a collection called `orderItems` is rendered as "Order Items".
 
+Occasionally though the desired name is not possible; either the name is a Java reserved word (eg "class"), or might require characters that are not valid, for example abbreviations.
 
-NOTE: see also xref:../ugbtb/ugbtb.adoc#_ugbtb_i18n[Internationalization]
+In such cases the name can be specified declaratively.
 
-== Class (object)
+It is also possible to specify a description declaratively; this is used as a tooltip in the UI.
 
-NOTE: FIXME - xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_named[`@DomainObjectLayout#named()`], xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_describedAs[`@DomainObjectLayout#describedAs()`]
+The table below summarizes the annotations available:
 
+.Names and descriptions
+[cols="1a,1a,1a", options="header"]
+|===
 
-== Property
+| Feature
+| Named
+| Description
 
-NOTE: FIXME - xref:../rgant/rgant.adoc#_rgant-PropertyLayout_named[`@PropertyLayout#named()`], xref:../rgant/rgant.adoc#_rgant-PropertyLayout_describedAs[`@PropertyLayout#describedAs()`]
 
+| Class
+| xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_named[`@DomainObjectLayout#named()`]
+| xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_describedAs[`@DomainObjectLayout#describedAs()`]
 
 
-== Collections
+| Property
+| xref:../rgant/rgant.adoc#_rgant-PropertyLayout_named[`@PropertyLayout#named()`]
+| xref:../rgant/rgant.adoc#_rgant-PropertyLayout_describedAs[`@PropertyLayout#describedAs()`]
 
-NOTE: FIXME - xref:../rgant/rgant.adoc#_rgant-CollectionLayout_named[`@CollectionLayout#named()`], xref:../rgant/rgant.adoc#_rgant-CollectionLayout_describedAs[`@CollectionLayout#describedAs()`]
+| Collection
+| xref:../rgant/rgant.adoc#_rgant-CollectionLayout_named[`@CollectionLayout#named()`]
+| xref:../rgant/rgant.adoc#_rgant-CollectionLayout_describedAs[`@CollectionLayout#describedAs()`]
 
+| Action
+| xref:../rgant/rgant.adoc#_rgant-ActionLayout_named[`@ActionLayout#named()`]
+| xref:../rgant/rgant.adoc#_rgant-ActionLayout_describedAs[`@ActionLayout#describedAs()`]
 
+| Action Parameters
+| xref:../rgant/rgant.adoc#_rgant-ParameterLayout_named[`@ParameterLayout#named()`]
+| xref:../rgant/rgant.adoc#_rgant-ParameterLayout_describedAs[`@ParameterLayout#describedAs()`]
 
-== Actions
-
-NOTE: FIXME - xref:../rgant/rgant.adoc#_rgant-ActionLayout_named[`@ActionLayout#named()`], xref:../rgant/rgant.adoc#_rgant-ActionLayout_describedAs[`@ActionLayout#describedAs()`]
-
-
-== Action Parameters
-
-NOTE: FIXME - xref:../rgant/rgant.adoc#_rgant-ParameterLayout_named[`@ParameterLayout#named()`], xref:../rgant/rgant.adoc#_rgant-ParameterLayout_describedAs[`@ParameterLayout#describedAs()`]
+|===
 
 
 [TIP]
@@ -43,5 +55,5 @@ If you're running on Java 8, then note that it's possible to write Isis applicat
 ====
 
 
-
-
+The framework also supports i18n: locale-specific names and descriptions.
+for more information, see the xref:../ugbtb/ugbtb.adoc#_ugbtb_i18n[beyond-the-basics] guide.

[49/58] [abbrv] isis git commit: completes ugfun.adoc - drop downs chapter

[da...@apache.org]

completes ugfun.adoc - drop downs chapter


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/3ce607ac
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/3ce607ac
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/3ce607ac

Branch: refs/heads/wip
Commit: 3ce607acb48922313db91b5e6af42ea5d908db9d
Parents: c1f4647
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Wed Apr 19 15:49:59 2017 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Thu Apr 20 09:09:31 2017 +0100

----------------------------------------------------------------------
 .../ugfun/_ugfun_drop-downs-and-defaults.adoc   | 192 ++++++++++++++++---
 1 file changed, 167 insertions(+), 25 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/3ce607ac/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_drop-downs-and-defaults.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_drop-downs-and-defaults.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_drop-downs-and-defaults.adoc
index 44bab58..6b2fef1 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_drop-downs-and-defaults.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_drop-downs-and-defaults.adoc
@@ -4,62 +4,204 @@
 :_basedir: ../../
 :_imagesdir: images/
 
-NOTE: FIXME
 
+Invoking an action whose parameters are primitives or values (int, date, string etc) is simple: the user can just type in or use a date picker.
+Invoking an action with a parameter of reference type (such as `Customer` or `Order`) requires the viewer to provide some mechanism by which the end-user can select the relevant instance.
 
+If the list of available options is fixed then the developer can provided a list a xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`] supporting method (for either and action parameter or when editing a property).
+These are rendered in a drop-down.
 
-== For Properties
+If the list of available options is much larger, then the developer can use an xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`] supporting method.
+The user user enters a few characters and this is used to search for matching reference(s), again rendered in a drop-down.
 
-NOTE: FIXME
+Similarly, when invoking an action, there may well be suitable defaults for the action arguments.
+For example, if placing an `Order` then -- even if the `Product` argument might not have a sensible default -- the quantity argument could reasonably be defaulted to 1.
+Or, the `Product` might indeed have a default, say the product previously placed by this user.
+The developer indicates this using a xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_default[`default...()`] supporting method.
 
-### Choices for Property
 
-NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`]
+== Choices and Default
 
-### Auto-complete for property
+For example, _choices_ for a property are specified using:
 
-NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`]
+[source,java]
+----
+@Getter @Setter
+private String paymentMethod;
 
-### Default for property
+public List<String> choicesPaymentMethod() {
+    return Arrays.asList("Visa", "Mastercard", "Amex");
+}
+----
 
-NOTE: FIXME -  xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_default[`default...()`]
+Note the "choices" prefix, while the suffix matches up with the getter.
 
+Or, for an action the _choices_ and a suitable _default_ method would be:
 
+[source,java]
+----
+public Order changePaymentMethod(
+                @ParameterLayout(named="Payment Method")
+                String paymentMethod) {
+    setPaymentMethod(paymentMethod);
+    return this;
+}
 
+public List<String> choices0ChangePaymentMethod() {
+    return Arrays.asList("Visa", "Mastercard", "Amex");
+}
 
-== For Action Parameters
+public String default0ChangePaymentMethod() {
+    return getPaymentMethod();
+}
+----
 
-NOTE: FIXME
+Note the "choices" and "default" prefix, the digit is the 0-based argument number, while the suffix matches up with the action's name.
 
-### Choices for action parameter
 
-NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`]
+== AutoComplete
 
-### Dependent choices for action params
+The _autocomplete_ is similar to _choices_, but accepts a string parameter, to search for matching results.
+A property for example might have:
 
-NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`]
+[source,java]
+----
+@Getter @Setter
+private Product product;
 
-### Auto-complete for action param
+public List<Product> autoCompleteProduct(@MinLength(2) String search) {
+    return productRepository.findByReferenceOrName(search);
+}
+----
 
-NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`]
+Note the "autoComplete" prefix, while (again) the suffix matches up with the getter.
+The `@MinLength(...)` annotation indicates the minimum number of characters that must be entered before a search is initiated.
 
-### Default for action param
+Actions are very similar:
 
-NOTE: FIXME -  xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_default[`default...()`]
+[source,java]
+----
+public Order changeProduct(Product product) {
+    setProduct(product);
+    return this;
+}
 
+public List<Product> autoComplete0Product(@MinLength(2) String search) {
+    return productRepository.findByReferenceOrName(search);
+}
+----
 
+An _autoComplete_ method can be used in conjunction with a _default_ method, but it doesn't make sense to provide both an _autoComplete_ and a _choices_ method.
 
 
-== For both Properties and Params
 
-NOTE: FIXME
+== "Globally" defined drop-downs
 
+Very often the set of available choices depends on the data type of the property/action parameter, rather than the individual property/parameter itself.
+And similarly the algorithm to search for references again may well depend only on that reference type.
 
-### Drop-down for limited number of instances
+In the case of _choices_, annotating a class as "bounded" (as in a "bounded" or fixed number of instances) means that a _choices_ drop-down will automatically be defined.
+For example:
 
-NOTE: FIXME - xref:../rgant/rgant.adoc#_rgant-DomainObject_bounded[`@DomainObject#bounded()`]
+[source,java]
+----
+@DomainObject(
+    bounded = true
+)
+public class Product { ... }
+----
+
+For more on this, see xref:../rgant/rgant.adoc#_rgant-DomainObject_bounded[`@DomainObject#bounded()`].
+
+Or, if the data type is an enum, then a drop-down will be provided automatically.
+A payment method is a good example of this:
+
+
+[source,java]
+----
+public enum PaymentMethod {
+    VISA, MASTERCARD, AMEX;
+}
+----
+
+Something similar can be achieved for _autoComplete_.
+Here the domain object indicates a repository query to execute.
+For example:
+
+[source,java]
+----
+@DomainObject(
+    autoCompleteRepository = Customers.class,
+    autoCompleteAction = "findByReferenceOrName"
+)
+public class Customer { ... }
+----
+
+with:
+
+[source,java]
+----
+@DomainService(nature=NatureOfService.VIEW_MENU_ONLY)
+public class Customers {
+    @Action(semantics=SemanticsOf.SAFE)
+    public List<Customer> findByReferenceOrName(@MinLength(3) String refOrName) {
+        ...
+    }
+}
+----
+
+For more on this, see xref:../rgant/rgant.adoc#_rgant-DomainObject_autoCompleteRepository[`@DomainObject#autoCompleteRepository()`].
+
+[TIP]
+====
+There's no need for the nominated method to be an actual action; any method of any domain service will do, so long as it accepts a string and returns the correct list.
+====
+
+
+== Multi-select action parameters
+
+As well as scalar values, action parameters can also be collections.
+For this to be valid, a _choices_ or _autoComplete_ supporting method must be provided.
+
+For example, suppose we want to "tag" or "label" an object:
+
+[source,java]
+----
+public StoryCard tag(List<Tag> tags) {
+    getTags().addAll(tags);
+}
+
+public List<Tag> autoCompleteTag(@MinLength(1) search) {
+    return tagRepository.findByName(search);
+}
+----
+
+
+
+
+== Dependent choices for action parameters
+
+For action it is also possible (in a limited form) to define dependencies between parameters.
+Specifically, if one parameter is a drop-down choice, then other drop-down choices can be derived from it.
+
+A good example is a category/sub-category:
+
+[source,java]
+----
+public ToDoItem categorize(Category category, Subcategory subcategory) {
+    setCategory(category);
+    setSubcategory(subcategory);
+}
+
+public List<Category> choices0Categorize() {
+    return categoryRepository.allCategories();
+}
+public List<Subcategory> choices1Categorize(Category category) {
+    return subcategoryRepository.findBy(category);
+}
+----
+
+Note how the _choices_ method for the 2nd parameter also accepts the first parameter.
 
 
-### Auto-complete (repository-based)
 
-xref:../rgant/rgant.adoc#_rgant-DomainObject_autoCompleteRepository[`@DomainObject#autoCompleteRepository()`]

[13/58] [abbrv] isis git commit: ISIS-1521: fixes xref links between guides

[da...@apache.org]

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout.adoc
index 2ce1cf5..df4b445 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout.adoc
@@ -11,7 +11,7 @@ The `@DomainObjectLayout` annotation applies to domain classes, collecting toget
 
 [NOTE]
 ====
-For view models that have been annotated with `@ViewModel` the equivalent xref:rgant.adoc#_rgant-ViewModelLayout[`@ViewModelLayout`] can be used.
+For view models that have been annotated with `@ViewModel` the equivalent xref:../rgant/rgant.adoc#_rgant-ViewModelLayout[`@ViewModelLayout`] can be used.
 ====
 
 
@@ -26,18 +26,18 @@ The table below summarizes the annotation's attributes.
 | Description
 
 
-|xref:rgant.adoc#_rgant-DomainObjectLayout_bookmarking[`bookmarking()`]
+|xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_bookmarking[`bookmarking()`]
 |`AS_ROOT`, `AS_CHILD`, `NEVER` +
 (`NEVER`)
 |whether (and how) this domain object should be automatically bookmarked
 
 
-|xref:rgant.adoc#_rgant-DomainObjectLayout_cssclass[`cssClass()`]
+|xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_cssclass[`cssClass()`]
 |Any string valid as a CSS class
-|the css class that a domain class (type) should have, to allow more targetted styling in xref:rgcfg.adoc#_rgcfg_application-specific_application-css[`application.css`]
+|the css class that a domain class (type) should have, to allow more targetted styling in xref:../rgcfg/rgcfg.adoc#_rgcfg_application-specific_application-css[`application.css`]
 
 
-|xref:rgant.adoc#_rgant-DomainObjectLayout_cssClassFa[`cssClassFa()`]
+|xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_cssClassFa[`cssClassFa()`]
 |Any valid link:http://fortawesome.github.io/Font-Awesome/[Font awesome] icon name
 |specify a font awesome icon for the action's menu link or icon. +
 
@@ -48,41 +48,41 @@ The table below summarizes the annotation's attributes.
 |Currently unused.
 
 
-|xref:rgant.adoc#_rgant-DomainObjectLayout_cssClassUiEvent[`cssClassUiEvent()`]
+|xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_cssClassUiEvent[`cssClassUiEvent()`]
 |subtype of `CssClassUiEvent` +
 (`CssClassUiEvent.Default`)
-|the event type to be posted to the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] to obtain a CSS class for the domain object.
+|the event type to be posted to the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] to obtain a CSS class for the domain object.
 
-|xref:rgant.adoc#_rgant-DomainObjectLayout_describedAs[`describedAs()`]
+|xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_describedAs[`describedAs()`]
 |String.
 |description of this class, eg to be rendered in a tooltip.
 
-|xref:rgant.adoc#_rgant-DomainObjectLayout_iconUiEvent[`iconUiEvent()`]
+|xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_iconUiEvent[`iconUiEvent()`]
 |subtype of `IconUiEvent` +
 (`IconUiEvent.Default`)
-|the event type to be posted to the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] to obtain the icon (name) for the domain object.
+|the event type to be posted to the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] to obtain the icon (name) for the domain object.
 
-|xref:rgant.adoc#_rgant-DomainObjectLayout_named[`named()`]
+|xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_named[`named()`]
 |String.
 |to override the name inferred from the action's name in code. +
 
 A typical use case is if the desired name is a reserved Java keyword, such as `default` or `package`.
 
 
-|xref:rgant.adoc#_rgant-DomainObjectLayout_paged[`paged()`]
+|xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_paged[`paged()`]
 |Positive integer
 |the page size for instances of this class when rendered within a table (as returned from an action invocation)
 
 
-|xref:rgant.adoc#_rgant-DomainObjectLayout_plural[`plural()`]
+|xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_plural[`plural()`]
 |String.
 |the plural name of the class
 
 
-|xref:rgant.adoc#_rgant-DomainObjectLayout_titleUiEvent[`titleUiEvent()`]
+|xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_titleUiEvent[`titleUiEvent()`]
 |subtype of `TitleUiEvent` +
 (`TitleUiEvent.Default`)
-|the event type to be posted to the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] to obtain the title for the domain object.
+|the event type to be posted to the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] to obtain the title for the domain object.
 
 |===
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_bookmarking.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_bookmarking.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_bookmarking.adoc
index df60f6e..5829ea1 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_bookmarking.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_bookmarking.adoc
@@ -6,7 +6,7 @@
 
 
 
-The `bookmarking()` attribute indicates that an entity is automatically bookmarked. This attribute is also supported for  xref:rgant.adoc#_rgant-Action_bookmarking[domain objects].
+The `bookmarking()` attribute indicates that an entity is automatically bookmarked. This attribute is also supported for  xref:../rgant/rgant.adoc#_rgant-Action_bookmarking[domain objects].
 
 (In the Wicket viewer), a link to a bookmarked object is shown in the bookmarks panel:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_cssClass.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_cssClass.adoc
index b9fefe8..27251fb 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_cssClass.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_cssClass.adoc
@@ -6,9 +6,9 @@
 
 
 
-The `cssClass()` attribute can be used to render additional CSS classes in the HTML (a wrapping `<div>`) that represents the domain object.   xref:rgcfg.adoc#_rgcfg_application-specific_application-css[Application-specific CSS] can then be used to target and adjust the UI representation of that particular element.
+The `cssClass()` attribute can be used to render additional CSS classes in the HTML (a wrapping `<div>`) that represents the domain object.   xref:../rgcfg/rgcfg.adoc#_rgcfg_application-specific_application-css[Application-specific CSS] can then be used to target and adjust the UI representation of that particular element.
 
-This attribute can also be applied to xref:rgant.adoc#_rgant-DomainObjectLayout_cssClass[domain objects], xref:rgant.adoc#_rgant-ViewModelLayout_cssClass[view models], xref:rgant.adoc#_rgant-ActionLayout_cssClass[actions] xref:rgant.adoc#_rgant-PropertyLayout_cssClass[properties],  xref:rgant.adoc#_rgant-CollectionLayout_cssClass[collections] and xref:rgant.adoc#_rgant-ParameterLayout_cssClass[parameters].
+This attribute can also be applied to xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_cssClass[domain objects], xref:../rgant/rgant.adoc#_rgant-ViewModelLayout_cssClass[view models], xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClass[actions] xref:../rgant/rgant.adoc#_rgant-PropertyLayout_cssClass[properties],  xref:../rgant/rgant.adoc#_rgant-CollectionLayout_cssClass[collections] and xref:../rgant/rgant.adoc#_rgant-ParameterLayout_cssClass[parameters].
 
 
 For example:
@@ -26,7 +26,7 @@ public class ToDoItem { ... }
 
 [NOTE]
 ====
-The similar xref:rgant.adoc#_rgant-DomainObjectLayout_cssClassFa[`@DomainObjectLayout#cssClassFa()`] annotation attribute is also used as a hint to apply CSS, but in particular to allow http://fortawesome.github.io/Font-Awesome/icons/[Font Awesome icons]
+The similar xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_cssClassFa[`@DomainObjectLayout#cssClassFa()`] annotation attribute is also used as a hint to apply CSS, but in particular to allow http://fortawesome.github.io/Font-Awesome/icons/[Font Awesome icons]
 to be rendered as the icon for classes.
 ====
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_cssClassFa.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_cssClassFa.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_cssClassFa.adoc
index 3cdac13..4b25012 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_cssClassFa.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_cssClassFa.adoc
@@ -8,9 +8,9 @@
 
 The `cssClassFa()` attribute is used to specify the name of a link:http://fortawesome.github.io/Font-Awesome/icons/[Font Awesome icon] name, to be rendered as the domain object's icon.
 
-These attributes can also be applied to xref:rgant.adoc#_rgant-ViewModelLayout_cssClassFa[view models] to specify the object's icon, and to xref:rgant.adoc#_rgant-ActionLayout_cssClassFa[actions] to specify an icon for the action's representation as a button or menu item.
+These attributes can also be applied to xref:../rgant/rgant.adoc#_rgant-ViewModelLayout_cssClassFa[view models] to specify the object's icon, and to xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClassFa[actions] to specify an icon for the action's representation as a button or menu item.
 
-If necessary the icon specified can be overridden by a particular object instance using the xref:rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`] method.
+If necessary the icon specified can be overridden by a particular object instance using the xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`] method.
 
 
 
@@ -32,7 +32,7 @@ The related `cssClassFaPosition()` attribute is currently unused for domain obje
 
 [TIP]
 ====
-The similar xref:rgant.adoc#_rgant-DomainObjectLayout_cssClass[`@DomainObjectLayout#cssClass()`] annotation attribute is also used as a hint
+The similar xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_cssClass[`@DomainObjectLayout#cssClass()`] annotation attribute is also used as a hint
 to apply CSS, but for wrapping the representation of an object or object
 member so that it can be styled in an application-specific way.
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_cssClassUiEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_cssClassUiEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_cssClassUiEvent.adoc
index 30a7004..0b1f983 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_cssClassUiEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_cssClassUiEvent.adoc
@@ -7,16 +7,16 @@
 
 Whenever a domain object is to be rendered, the framework fires off an CSS class UI event to obtain a CSS class to use
 in any wrapping ``<div>``s and ``<span>``s that render the domain object.  This is as an alternative to implementing
-xref:rgcms.adoc#_rgcms_methods_reserved_cssClass[`cssClass()`] reserved method.  (If `cssClass()` is present, then
+xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_cssClass[`cssClass()`] reserved method.  (If `cssClass()` is present, then
 it will take precedence).
 
-Subscribers subscribe through the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] and can
+Subscribers subscribe through the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] and can
 use obtain a reference to the domain object from the event.  From this they can, if they wish, specify a CSS class for
 the domain object using the event's API.
 
 [NOTE]
 ====
-The feature was originally introduced so that xref:rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`]-annotated
+The feature was originally introduced so that xref:../rgant/rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`]-annotated
 xref:ugbtb.adoc#_ugbtb_view-models[view model]s could be kept as minimal as possible, just defining the data.
 UI events allow subscribers to provide UI hints, while xref:ugbtb.adoc#_ugbtb_decoupling_mixins[mixin]s can be used to provide the behaviour.
 ====
@@ -56,7 +56,7 @@ The benefit is that subscribers can be more targeted as to the events that they
 == Subscribers
 
 Subscribers (which must be domain services) subscribe using either the link:https://github.com/google/guava[Guava] API
-or (if the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] has been appropriately configured)
+or (if the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] has been appropriately configured)
 using the link:http://www.axonframework.org/[Axon Framework] API.  The examples below use the Guava API.
 
 Subscribers can be either coarse-grained (if they subscribe to the top-level event type):
@@ -119,8 +119,8 @@ then no event will be posted.
 == Raising events programmatically
 
 Normally events are only raised for interactions through the UI. However, events can be raised programmatically either
-by calling the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] API directly, or as a result
-of calling the xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`]'s
+by calling the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] API directly, or as a result
+of calling the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`]'s
 `cssClassOf(...)` method.
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_describedAs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_describedAs.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_describedAs.adoc
index d275d3e..0c026da 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_describedAs.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_describedAs.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-The `describedAs()` attribute is used to provide a short description of the domain object to the user.  In the xref:ugvw.adoc#[Wicket viewer] it is displayed as a 'tool tip'.  The attribute can also be specified for xref:rgant.adoc#_rgant-CollectionLayout_describedAs[collections],  xref:rgant.adoc#_rgant-PropertyLayout_describedAs[properties], xref:rgant.adoc#_rgant-ActionLayout_describedAs[actions], xref:rgant.adoc#_rgant-ParameterLayout_describedAs[parameters] and xref:rgant.adoc#_rgant-ViewModelLayout_describedAs[view models].
+The `describedAs()` attribute is used to provide a short description of the domain object to the user.  In the xref:ugvw.adoc#[Wicket viewer] it is displayed as a 'tool tip'.  The attribute can also be specified for xref:../rgant/rgant.adoc#_rgant-CollectionLayout_describedAs[collections],  xref:../rgant/rgant.adoc#_rgant-PropertyLayout_describedAs[properties], xref:../rgant/rgant.adoc#_rgant-ActionLayout_describedAs[actions], xref:../rgant/rgant.adoc#_rgant-ParameterLayout_describedAs[parameters] and xref:../rgant/rgant.adoc#_rgant-ViewModelLayout_describedAs[view models].
 
 For example:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_iconUiEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_iconUiEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_iconUiEvent.adoc
index fb97a35..2a48a2e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_iconUiEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_iconUiEvent.adoc
@@ -7,17 +7,17 @@
 
 Whenever a domain object is to be rendered, the framework fires off an icon UI event to obtain an icon (name) for the
 object (if possible). This is as an alternative to implementing
-xref:rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`] reserved method.  (If `iconName()` is present, then
+xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`] reserved method.  (If `iconName()` is present, then
 it will take precedence).
 
-Subscribers subscribe through the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] and can
+Subscribers subscribe through the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] and can
 use obtain a reference to the domain object from the event.  From this they can, if they wish, specify an icon name for
 the domain object using the event's API.
 
 
 [NOTE]
 ====
-The feature was originally introduced so that xref:rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`]-annotated
+The feature was originally introduced so that xref:../rgant/rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`]-annotated
 xref:ugbtb.adoc#_ugbtb_view-models[view model]s could be kept as minimal as possible, just defining the data.
 UI events allow subscribers to provide UI hints, while xref:ugbtb.adoc#_ugbtb_decoupling_mixins[mixin]s can be used to provide the behaviour.
 ====
@@ -57,7 +57,7 @@ The benefit is that subscribers can be more targeted as to the events that they
 == Subscribers
 
 Subscribers (which must be domain services) subscribe using either the link:https://github.com/google/guava[Guava] API
-or (if the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] has been appropriately configured)
+or (if the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] has been appropriately configured)
 using the link:http://www.axonframework.org/[Axon Framework] API.  The examples below use the Guava API.
 
 Subscribers can be either coarse-grained (if they subscribe to the top-level event type):
@@ -115,8 +115,8 @@ then no event will be posted.
 == Raising events programmatically
 
 Normally events are only raised for interactions through the UI. However, events can be raised programmatically either
-by calling the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] API directly, or as a result
-of calling the xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`]'s
+by calling the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] API directly, or as a result
+of calling the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`]'s
 `iconNameOf(...)` method.
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_named.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_named.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_named.adoc
index 97c628c..4302409 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_named.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_named.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-The `named()` attribute explicitly specifies the domain object's name, overriding the name that would normally be inferred from the Java source code.  The attribute can also be specified for xref:rgant.adoc#_rgant-ActionLayout_named[actions], xref:rgant.adoc#_rgant-CollectionLayout_named[collections], xref:rgant.adoc#_rgant-PropertyLayout_named[properties], xref:rgant.adoc#_rgant-ParameterLayout_named[parameters], xref:rgant.adoc#_rgant-ViewModelLayout_named[view models] and xref:rgant.adoc#_rgant-DomainServiceLayout_named[domain services].
+The `named()` attribute explicitly specifies the domain object's name, overriding the name that would normally be inferred from the Java source code.  The attribute can also be specified for xref:../rgant/rgant.adoc#_rgant-ActionLayout_named[actions], xref:../rgant/rgant.adoc#_rgant-CollectionLayout_named[collections], xref:../rgant/rgant.adoc#_rgant-PropertyLayout_named[properties], xref:../rgant/rgant.adoc#_rgant-ParameterLayout_named[parameters], xref:../rgant/rgant.adoc#_rgant-ViewModelLayout_named[view models] and xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_named[domain services].
 
 
 [TIP]
@@ -26,7 +26,7 @@ public class CustomerImpl implements Customer{
 }
 ----
 
-It's also possible to specify a xref:rgant.adoc#_rgant-DomainObjectLayout_plural[plural form] of the name, used by the framework when rendering a standalone collection of the domain object.
+It's also possible to specify a xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_plural[plural form] of the name, used by the framework when rendering a standalone collection of the domain object.
 
 
 [TIP]

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_paged.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_paged.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_paged.adoc
index ccf0192..8380c1b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_paged.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_paged.adoc
@@ -6,7 +6,7 @@
 
 
 
-The `paged()` attribute specifies the number of rows to display in a standalone collection, as returned from an action invocation. This attribute can also be applied to xref:rgant.adoc#_rgant-CollectionLayout_paged[collections] and xref:rgant.adoc#_rgant-ViewModelLayout_paged[view models].
+The `paged()` attribute specifies the number of rows to display in a standalone collection, as returned from an action invocation. This attribute can also be applied to xref:../rgant/rgant.adoc#_rgant-CollectionLayout_paged[collections] and xref:../rgant/rgant.adoc#_rgant-ViewModelLayout_paged[view models].
 
 
 [WARNING]
@@ -28,6 +28,6 @@ public class Order {
 ----
 
 
-It is also possible to specify a global default for the page size of standalone collections, using the xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.viewer.paged.standalone`.
+It is also possible to specify a global default for the page size of standalone collections, using the xref:../rgcfg/rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.viewer.paged.standalone`.
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_plural.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_plural.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_plural.adoc
index 1a6191f..60c38fc 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_plural.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_plural.adoc
@@ -10,7 +10,7 @@ When Apache Isis displays a standalone collection of several objects, it will la
 
 By default the plural name will be derived from the end of the singular name, with support for some basic English language defaults (eg using "ies" for names ending with a "y").
 
-The `plural()` attribute allows the plural form of the class name to be specified explicitly.  This attribute is also supported for xref:rgant.adoc#_rgant-ViewModelLayout_plural[view models].
+The `plural()` attribute allows the plural form of the class name to be specified explicitly.  This attribute is also supported for xref:../rgant/rgant.adoc#_rgant-ViewModelLayout_plural[view models].
 
 For example:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_titleUiEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_titleUiEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_titleUiEvent.adoc
index 67ca08e..a36a421 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_titleUiEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_titleUiEvent.adoc
@@ -6,17 +6,17 @@
 
 
 Whenever a domain object is to be rendered, the framework fires off a title UI event to obtain a title for the object.
-This is as an alternative to implementing xref:rgcms.adoc#_rgcms_methods_reserved_title[`title()`] reserved method, or
-using the xref:rgant.adoc#_rgant-Title[`@Title`] annotation, within the class itself.  (If either
+This is as an alternative to implementing xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_title[`title()`] reserved method, or
+using the xref:../rgant/rgant.adoc#_rgant-Title[`@Title`] annotation, within the class itself.  (If either
 `title()` or `@Title` are present, then they will take precedence).
 
-Subscribers subscribe through the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] and can
+Subscribers subscribe through the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] and can
 use obtain a reference to the domain object from the event.  From this they can, if they wish, specify a title for
 the domain object using the event's API.
 
 [NOTE]
 ====
-The feature was originally introduced so that xref:rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`]-annotated
+The feature was originally introduced so that xref:../rgant/rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`]-annotated
 xref:ugbtb.adoc#_ugbtb_view-models[view model]s could be kept as minimal as possible, just defining the data.
 UI events allow subscribers to provide UI hints, while xref:ugbtb.adoc#_ugbtb_decoupling_mixins[mixin]s can be used to provide the behaviour.
 ====
@@ -56,7 +56,7 @@ The benefit is that subscribers can be more targeted as to the events that they
 == Subscribers
 
 Subscribers (which must be domain services) subscribe using either the link:https://github.com/google/guava[Guava] API
-or (if the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] has been appropriately configured)
+or (if the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] has been appropriately configured)
 using the link:http://www.axonframework.org/[Axon Framework] API.  The examples below use the Guava API.
 
 Subscribers can be either coarse-grained (if they subscribe to the top-level event type):
@@ -115,6 +115,6 @@ thn no event will be posted.
 == Raising events programmatically
 
 Normally events are only raised for interactions through the UI. However, events can be raised programmatically either
-by calling the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] API directly, or as a result
-of calling the xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`]'s
+by calling the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] API directly, or as a result
+of calling the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`]'s
 `titleOf(...)` method.

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_auditing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_auditing.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_auditing.adoc
index 9901370..82a0d41 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_auditing.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_auditing.adoc
@@ -6,11 +6,11 @@
 
 
 The `auditing()` attribute indicates that if the object is modified, then each of its changed properties should be
-submitted to the xref:rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`] (if one has been configured), or to
+submitted to the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`] (if one has been configured), or to
 any
 
 The default value for the attribute is `AS_CONFIGURED`, meaning that the
-xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.services.audit.objects` is used to determine the
+xref:../rgcfg/rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.services.audit.objects` is used to determine the
 whether the action is audited:
 
 * `all` +

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_autoCompleteRepository.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_autoCompleteRepository.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_autoCompleteRepository.adoc
index 6c730ef..2fa8299 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_autoCompleteRepository.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_autoCompleteRepository.adoc
@@ -14,7 +14,7 @@ For example, this might search for a customer by their name or number.  Or it co
 
 [TIP]
 ====
-If you require additional control - for example restricting the returned results based on the object being interacted with - then use the xref:rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`] supporting method instead.
+If you require additional control - for example restricting the returned results based on the object being interacted with - then use the xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`] supporting method instead.
 ====
 
 
@@ -78,7 +78,7 @@ public class Customers {
 ----
 <1> end-user must enter minimum number of characters to trigger the query
 
-The autocomplete action can also be a regular method, annotated using xref:rgant.adoc#_rgant_Programmatic[`@Programmatic`]:
+The autocomplete action can also be a regular method, annotated using xref:../rgant/rgant.adoc#_rgant_Programmatic[`@Programmatic`]:
 
 [source,java]
 ----
@@ -95,5 +95,5 @@ public class Customers {
 
 [IMPORTANT]
 ====
-The method specified must be an action, that is, part of the Isis metamodel.  Said another way: it must not be annotated with xref:rgant.adoc#_rgant-Programmatic[`@Programmatic`].  However, it *can* be hidden or placed on a domain service with xref:rgant.adoc#_rgant-DomainService_nature[nature] of `DOMAIN`, such that the action would not be rendered otherwise in the UI.  Also, the action cannot be xref:rgant.adoc#_rgant-Action_restrictTo[restricted to] prototyping only.
+The method specified must be an action, that is, part of the Isis metamodel.  Said another way: it must not be annotated with xref:../rgant/rgant.adoc#_rgant-Programmatic[`@Programmatic`].  However, it *can* be hidden or placed on a domain service with xref:../rgant/rgant.adoc#_rgant-DomainService_nature[nature] of `DOMAIN`, such that the action would not be rendered otherwise in the UI.  Also, the action cannot be xref:../rgant/rgant.adoc#_rgant-Action_restrictTo[restricted to] prototyping only.
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_bounded.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_bounded.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_bounded.adoc
index 9f2f4f2..40a2c64 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_bounded.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_bounded.adoc
@@ -28,7 +28,7 @@ public class Currency {
 
 [TIP]
 ====
-There is nothing to prevent you from using this attribute for regular mutable entities, and indeed this is sometimes worth doing during early prototyping.  However, if there is no realistic upper bound to the number of instances of an entity that might be created, generally you should use xref:rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`] supporting method or the xref:rgant.adoc#_rgant-DomainObject_autoCompleteRepository[`@DomainObject#autoCompleteRepository()`] attribute instead.
+There is nothing to prevent you from using this attribute for regular mutable entities, and indeed this is sometimes worth doing during early prototyping.  However, if there is no realistic upper bound to the number of instances of an entity that might be created, generally you should use xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`] supporting method or the xref:../rgant/rgant.adoc#_rgant-DomainObject_autoCompleteRepository[`@DomainObject#autoCompleteRepository()`] attribute instead.
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_createdLifecycleEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_createdLifecycleEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_createdLifecycleEvent.adoc
index 79e2a2c..71355d5 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_createdLifecycleEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_createdLifecycleEvent.adoc
@@ -5,11 +5,11 @@
 :_imagesdir: images/
 
 
-Whenever a domain object is instantiated or otherwise becomes known to the framework, a "created" lifecycle event is fired.  This is typically when the xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`]'s xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-creation-api[`newTransientInstance()`] is called;
+Whenever a domain object is instantiated or otherwise becomes known to the framework, a "created" lifecycle event is fired.  This is typically when the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`]'s xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-creation-api[`newTransientInstance()`] is called;
 it will also happen if the object is simply instantiated with `new(...)`, and then the container's
-xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer_services-api[`injectServicesInto(...)`] method is called.
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer_services-api[`injectServicesInto(...)`] method is called.
 
-Subscribers subscribe through the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] and can
+Subscribers subscribe through the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] and can
 use the event to obtain a reference to the object just created.  The subscriber could then, for example, update the
 object, eg looking up state from some external datastore.
 
@@ -49,7 +49,7 @@ The benefit is that subscribers can be more targeted as to the events that they
 == Subscribers
 
 Subscribers (which must be domain services) subscribe using either the link:https://github.com/google/guava[Guava] API
-or (if the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] has been appropriately configured)
+or (if the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] has been appropriately configured)
 using the link:http://www.axonframework.org/[Axon Framework] API.  The examples below use the Guava API.
 
 Subscribers can be either coarse-grained (if they subscribe to the top-level event type):

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_editing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_editing.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_editing.adoc
index fd852eb..82e7be7 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_editing.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_editing.adoc
@@ -8,7 +8,7 @@
 
 The `editing()` attribute determines whether a domain object's properties and collections are not editable (are read-only).
 
-The default is `AS_CONFIGURED`, meaning that the xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.objects.editing` is used to determine the whether the object is modifiable:
+The default is `AS_CONFIGURED`, meaning that the xref:../rgcfg/rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.objects.editing` is used to determine the whether the object is modifiable:
 
 * `true` +
 +

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_loadedLifecycleEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_loadedLifecycleEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_loadedLifecycleEvent.adoc
index f83a82c..4c4536b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_loadedLifecycleEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_loadedLifecycleEvent.adoc
@@ -7,7 +7,7 @@
 
 Whenever a persistent domain object is loaded from the database, a "loaded" lifecycle event is fired.
 
-Subscribers subscribe through the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] and can
+Subscribers subscribe through the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] and can
 use the event to obtain a reference to the domain object just loaded.  The subscriber could then, for example, update
 or default values on the object (eg to support on-the-fly migration scenarios).
 
@@ -46,7 +46,7 @@ The benefit is that subscribers can be more targeted as to the events that they
 == Subscribers
 
 Subscribers (which must be domain services) subscribe using either the link:https://github.com/google/guava[Guava] API
-or (if the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] has been appropriately configured)
+or (if the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] has been appropriately configured)
 using the link:http://www.axonframework.org/[Axon Framework] API.  The examples below use the Guava API.
 
 Subscribers can be either coarse-grained (if they subscribe to the top-level event type):

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_nature.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_nature.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_nature.adoc
index 755bbec..a0e64c9 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_nature.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_nature.adoc
@@ -44,7 +44,7 @@ The identity of an inmemory entity is determined solely by the state of entity's
 +
 indicates that the domain object is part of the domain layer, and is contributing behaviour to objects of some other type as a mixin (also known as a trait).
 
-Equivalent to annotating with xref:rgant.adoc#_rgant-Mixin[`@Mixin`].  For further discussion on using mixins, see xref:ugbtb.adoc#_ugbtb_decoupling_mixins[mixins] in the user guide.
+Equivalent to annotating with xref:../rgant/rgant.adoc#_rgant-Mixin[`@Mixin`].  For further discussion on using mixins, see xref:ugbtb.adoc#_ugbtb_decoupling_mixins[mixins] in the user guide.
 
 
 * `VIEW_MODEL` +
@@ -53,7 +53,7 @@ indicates that the domain object is conceptually part of the application layer,
 
 The identity of an inmemory entity is determined solely by the state of entity's properties.  The framework will automatically recreate the domain object each time it is interacted with.
 
-Those natures that indicate the domain object is an entity (of some sort or another) mean then that the domain object is considered to be part of the domain model layer.  As such the domain object's class cannot be annotated with xref:rgant.adoc#_rgant-ViewModel[`@ViewModel`] or implement the xref:rgcms.adoc#_rgcms_classes_super_ViewModel[`ViewModel`] interface.
+Those natures that indicate the domain object is an entity (of some sort or another) mean then that the domain object is considered to be part of the domain model layer.  As such the domain object's class cannot be annotated with xref:../rgant/rgant.adoc#_rgant-ViewModel[`@ViewModel`] or implement the xref:../rgcms/rgcms.adoc#_rgcms_classes_super_ViewModel[`ViewModel`] interface.
 
 
 [NOTE]

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_objectType.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_objectType.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_objectType.adoc
index 14fa17a..adf3c50 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_objectType.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_objectType.adoc
@@ -11,12 +11,12 @@ This value is used internally to generate a string representation of an objects
 This can appear in several contexts, including:
 
 * as the value of `Bookmark#getObjectType()` and in the `toString()` value of `Bookmark`
- (see xref:rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`])
+ (see xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`])
  ** and thus in the "table-of-two-halves" pattern, as per (non-ASF) http://github.com/isisaddons/isis-module-poly[Isis addons' poly] module
-* in the serialization of `OidDto` in the xref:rgcms.adoc#_rgcms_schema-cmd[command] and xref:rgcms.adoc#_rgcms_schema-ixn[interaction] schemas
+* in the serialization of `OidDto` in the xref:../rgcms/rgcms.adoc#_rgcms_schema-cmd[command] and xref:../rgcms/rgcms.adoc#_rgcms_schema-ixn[interaction] schemas
 * in the URLs of the xref:ugvro.adoc#[RestfulObjects viewer]
 * in the URLs of the xref:ugvw.adoc#[Wicket viewer] (in general and in particular if xref:ugvw.adoc#_ugvw_features_hints-and-copy-url[copying URLs])
-* in XML snapshots generated by the xref:rgsvc.adoc#_rgsvc_api_XmlSnapshotService[`XmlSnapshotService`]
+* in XML snapshots generated by the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_XmlSnapshotService[`XmlSnapshotService`]
 
 
 
@@ -39,9 +39,9 @@ public class Order {
 
 The rules of precedence are:
 
-1. xref:rgant.adoc#_rgant_Discriminator[`@Discriminator`]
-2. `@DomainObject#objectType`, or xref:rgant.adoc#_rgant_aaa_deprecated[`@ObjectType`] (deprecated)
-3. xref:rgant.adoc#_rgant_PersistenceCapable[`@PersistenceCapable`], if at least the `schema` attribute is defined.  +
+1. xref:../rgant/rgant.adoc#_rgant_Discriminator[`@Discriminator`]
+2. `@DomainObject#objectType`, or xref:../rgant/rgant.adoc#_rgant_aaa_deprecated[`@ObjectType`] (deprecated)
+3. xref:../rgant/rgant.adoc#_rgant_PersistenceCapable[`@PersistenceCapable`], if at least the `schema` attribute is defined.  +
 +
 If both `schema` and `table` are defined, then the value is "`schema.table`".
 If only `schema` is defined, then the value is "`schema.className`".

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_persistedLifecycleEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_persistedLifecycleEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_persistedLifecycleEvent.adoc
index cf34e34..a948b48 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_persistedLifecycleEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_persistedLifecycleEvent.adoc
@@ -8,7 +8,7 @@
 Whenever a (just created, still transient) domain object has been saved (INSERTed in)to the database, a "persisted" lifecycle
 event is fired.
 
-Subscribers subscribe through the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] and can
+Subscribers subscribe through the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] and can
 use the event to obtain a reference to the domain object.  The subscriber could then, for example, maintain an
 external datastore.
 
@@ -52,7 +52,7 @@ The benefit is that subscribers can be more targeted as to the events that they
 == Subscribers
 
 Subscribers (which must be domain services) subscribe using either the link:https://github.com/google/guava[Guava] API
-or (if the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] has been appropriately configured)
+or (if the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] has been appropriately configured)
 using the link:http://www.axonframework.org/[Axon Framework] API.  The examples below use the Guava API.
 
 Subscribers can be either coarse-grained (if they subscribe to the top-level event type):

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_persistingLifecycleEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_persistingLifecycleEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_persistingLifecycleEvent.adoc
index ae1f54a..20a5194 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_persistingLifecycleEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_persistingLifecycleEvent.adoc
@@ -8,7 +8,7 @@
 Whenever a (just created, still transient) domain object is about to be saved (INSERTed in)to the database, a "persisting" lifecycle
 event is fired.
 
-Subscribers subscribe through the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] and can
+Subscribers subscribe through the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] and can
 use the event to obtain a reference to the domain object.  The subscriber could then, for example, update the object,
 or it could use it maintain an external datastore.  One possible application is to maintain a full-text search database using
 link:https://lucene.apache.org/[Apache Lucene] or similar.
@@ -17,7 +17,7 @@ link:https://lucene.apache.org/[Apache Lucene] or similar.
 ====
 Another use case is to maintain "last updated by"/"last updated at" properties.  While you can roll your own, note that
 the framework provides built-in support for this use case through the
-xref:rgcms.adoc#_rgcms_classes_roles_Timestampable[`Timestampable`] role interface.
+xref:../rgcms/rgcms.adoc#_rgcms_classes_roles_Timestampable[`Timestampable`] role interface.
 ====
 
 By default the event raised is `ObjectPersistingEvent.Default`. For example:
@@ -55,7 +55,7 @@ The benefit is that subscribers can be more targeted as to the events that they
 == Subscribers
 
 Subscribers (which must be domain services) subscribe using either the link:https://github.com/google/guava[Guava] API
-or (if the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] has been appropriately configured)
+or (if the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] has been appropriately configured)
 using the link:http://www.axonframework.org/[Axon Framework] API.  The examples below use the Guava API.
 
 Subscribers can be either coarse-grained (if they subscribe to the top-level event type):

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_publishing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_publishing.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_publishing.adoc
index 173f5d5..b4263a4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_publishing.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_publishing.adoc
@@ -7,15 +7,15 @@
 
 
 The `publishing()` attribute determines whether and how a modified object instance is published via the registered
-implementation of a xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`]) or
-xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`].  This attribute is also supported
-for xref:rgant.adoc#_rgant-Action_publishing[actions], where it controls whether action invocations are published as
-events, and for xref:rgant.adoc#_rgant_Property_publishing[`@Property#publishing()`], where it controls whether
+implementation of a xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`]) or
+xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`].  This attribute is also supported
+for xref:../rgant/rgant.adoc#_rgant-Action_publishing[actions], where it controls whether action invocations are published as
+events, and for xref:../rgant/rgant.adoc#_rgant_Property_publishing[`@Property#publishing()`], where it controls whether
 property edits are published as events.
 
 A common use case is to notify external "downstream" systems of changes in the state of the Isis application.
 
-The default value for the attribute is `AS_CONFIGURED`, meaning that the xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.services.publish.objects` is used to determine the whether the action is published:
+The default value for the attribute is `AS_CONFIGURED`, meaning that the xref:../rgcfg/rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.services.publish.objects` is used to determine the whether the action is published:
 
 * `all` +
 +
@@ -58,6 +58,6 @@ this should avoid the necessity to query back for additional information.
 [WARNING]
 ====
 Be aware that this attribute is only honoured by the (deprecated)
-xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`], so should itself be considered as deprecated.  It
-is ignored by the replacement xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`],
+xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`], so should itself be considered as deprecated.  It
+is ignored by the replacement xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`],
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_removingLifecycleEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_removingLifecycleEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_removingLifecycleEvent.adoc
index 190725a..fa7e0f2 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_removingLifecycleEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_removingLifecycleEvent.adoc
@@ -8,7 +8,7 @@
 Whenever a (persistent) domain object is about to be removed (DELETEd) from the database, a "removing"
 lifecycle event is fired.
 
-Subscribers subscribe through the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] and can
+Subscribers subscribe through the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] and can
 use the event to obtain a reference to the domain object.  The subscriber could then, for example, could use it
 maintain an external datastore.  One possible application is to maintain a full-text search database
 using link:https://lucene.apache.org/[Apache Lucene] or similar.
@@ -17,7 +17,7 @@ using link:https://lucene.apache.org/[Apache Lucene] or similar.
 ====
 Another use case is to maintain "last updated by"/"last updated at" properties.  While you can roll your own, note that
 the framework provides built-in support for this use case through the
-xref:rgcms.adoc#_rgcms_classes_roles_Timestampable[`Timestampable`] role interface.
+xref:../rgcms/rgcms.adoc#_rgcms_classes_roles_Timestampable[`Timestampable`] role interface.
 ====
 
 By default the event raised is `ObjectRemovingEvent.Default`. For example:
@@ -55,7 +55,7 @@ The benefit is that subscribers can be more targeted as to the events that they
 == Subscribers
 
 Subscribers (which must be domain services) subscribe using either the link:https://github.com/google/guava[Guava] API
-or (if the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] has been appropriately configured)
+or (if the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] has been appropriately configured)
 using the link:http://www.axonframework.org/[Axon Framework] API.  The examples below use the Guava API.
 
 Subscribers can be either coarse-grained (if they subscribe to the top-level event type):

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_updatedLifecycleEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_updatedLifecycleEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_updatedLifecycleEvent.adoc
index da3845b..6996a45 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_updatedLifecycleEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_updatedLifecycleEvent.adoc
@@ -8,7 +8,7 @@
 Whenever a (persistent) domain object has been modified and has been updated in the database, an "updated" lifecycle
 event is fired.
 
-Subscribers subscribe through the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] and can
+Subscribers subscribe through the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] and can
 use the event to obtain a reference to the domain object.
 
 [WARNING]
@@ -51,7 +51,7 @@ The benefit is that subscribers can be more targeted as to the events that they
 == Subscribers
 
 Subscribers (which must be domain services) subscribe using either the link:https://github.com/google/guava[Guava] API
-or (if the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] has been appropriately configured)
+or (if the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] has been appropriately configured)
 using the link:http://www.axonframework.org/[Axon Framework] API.  The examples below use the Guava API.
 
 Subscribers can be either coarse-grained (if they subscribe to the top-level event type):

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_updatingLifecycleEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_updatingLifecycleEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_updatingLifecycleEvent.adoc
index af5d2fb..d824947 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_updatingLifecycleEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_updatingLifecycleEvent.adoc
@@ -8,7 +8,7 @@
 Whenever a (persistent) domain object has been modified and is about to be updated to the database, an "updating"
 lifecycle event is fired.
 
-Subscribers subscribe through the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] and can
+Subscribers subscribe through the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] and can
 use the event to obtain a reference to the domain object.  The subscriber could then, for example, update the object,
 or it could use it maintain an external datastore.  One possible application is to maintain a full-text search database
 using link:https://lucene.apache.org/[Apache Lucene] or similar.
@@ -17,7 +17,7 @@ using link:https://lucene.apache.org/[Apache Lucene] or similar.
 ====
 Another use case is to maintain "last updated by"/"last updated at" properties.  While you can roll your own, note that
 the framework provides built-in support for this use case through the
-xref:rgcms.adoc#_rgcms_classes_roles_Timestampable[`Timestampable`] role interface.
+xref:../rgcms/rgcms.adoc#_rgcms_classes_roles_Timestampable[`Timestampable`] role interface.
 ====
 
 By default the event raised is `ObjectUpdatingEvent.Default`. For example:
@@ -55,7 +55,7 @@ The benefit is that subscribers can be more targeted as to the events that they
 == Subscribers
 
 Subscribers (which must be domain services) subscribe using either the link:https://github.com/google/guava[Guava] API
-or (if the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] has been appropriately configured)
+or (if the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] has been appropriately configured)
 using the link:http://www.axonframework.org/[Axon Framework] API.  The examples below use the Guava API.
 
 Subscribers can be either coarse-grained (if they subscribe to the top-level event type):

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainService.adoc
index 1b00e29..a1e1d18 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainService.adoc
@@ -22,26 +22,26 @@ The table below summarizes the annotation's attributes.
 | Description
 
 
-|xref:rgant.adoc#_rgant-DomainService_nature[`nature()`]
+|xref:../rgant/rgant.adoc#_rgant-DomainService_nature[`nature()`]
 |`VIEW`, `VIEW_MENU_ONLY`, `VIEW_CONTRIBUTIONS_ONLY`, `VIEW_REST_ONLY`, `DOMAIN` (`VIEW`)
 |the nature of this service: providing actions for menus, or as contributed actions, or for the xref:ugvro.adoc#[RestfulObjects REST API], or neither
 
 
-|xref:rgant.adoc#_rgant-DomainService_objectType[`objectType()`]
+|xref:../rgant/rgant.adoc#_rgant-DomainService_objectType[`objectType()`]
 |
-|equivalent to xref:rgant.adoc#_rgant_DomainObject_objectType[`@DomainObject#objectType()`], specifies the objectType of the service.
+|equivalent to xref:../rgant/rgant.adoc#_rgant_DomainObject_objectType[`@DomainObject#objectType()`], specifies the objectType of the service.
 
 The instanceId for services is always "1".
 
 
-|xref:rgant.adoc#_rgant-DomainService_repositoryFor[`repositoryFor()`]
+|xref:../rgant/rgant.adoc#_rgant-DomainService_repositoryFor[`repositoryFor()`]
 |
 |if this domain service acts as a repository for an entity type, specify that entity type.  This is used to determine an icon to use for the service (eg as shown in action prompts).
 
 
 |`menuOrder()`
 |
-|Deprecated in 1.8.0; use instead xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`]
+|Deprecated in 1.8.0; use instead xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`]
 
 |===
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainServiceLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainServiceLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainServiceLayout.adoc
index 90e54de..10674c7 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainServiceLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainServiceLayout.adoc
@@ -25,17 +25,17 @@ The table below summarizes the annotation's attributes.
 | Description
 
 
-|xref:rgant.adoc#_rgant-DomainServiceLayout_menuBar[`menuBar()`]
+|xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuBar[`menuBar()`]
 |`PRIMARY`, `SECONDARY`, `TERTIARY` (`PRIMARY`).
 |the menubar in which the menu that holds this service's actions should reside.
 
 
-|xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`menuOrder()`]
+|xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`menuOrder()`]
 |
 |the order of the service's menu with respect to other service's.
 
 
-|xref:rgant.adoc#_rgant-DomainServiceLayout_named[`named()`]
+|xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_named[`named()`]
 |string, eg "Customers"
 |name of this class (overriding the name derived from its name in code)
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainServiceLayout_menuBar.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainServiceLayout_menuBar.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainServiceLayout_menuBar.adoc
index 1f0b649..f300e81 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainServiceLayout_menuBar.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainServiceLayout_menuBar.adoc
@@ -33,7 +33,7 @@ Domain services placed on the `TERTIARY` appear in the menu bar associated with
 image::{_imagesdir}reference-annotations/DomainServiceLayout/menuBar-tertiary.png[width="720px",link="{_imagesdir}reference-annotations/DomainServiceLayout/menuBar-tertiary.png"]
 
 
-The grouping of multiple domain services actions within a single drop-down is managed by the xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] attribute.
+The grouping of multiple domain services actions within a single drop-down is managed by the xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] attribute.
 
 
 [NOTE]

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainServiceLayout_menuOrder.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainServiceLayout_menuOrder.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainServiceLayout_menuOrder.adoc
index ee56c12..95fc52b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainServiceLayout_menuOrder.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainServiceLayout_menuOrder.adoc
@@ -11,8 +11,8 @@ The `menuOrder()` attribute determines the ordering of a domain service's action
 
 The algorithm works as follows:
 
-* first, the xref:rgant.adoc#_rgant-DomainServiceLayout_menuBar[`menuBar()`] determines which of the three menu bars the service's actions should be rendered
-* then, the domain service's top-level name (typically explicitly specified using xref:rgant.adoc#_rgant-DomainServiceLayout_named[`named()`]) is used to determine the top-level menu item to be rendered on the menu bar
+* first, the xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuBar[`menuBar()`] determines which of the three menu bars the service's actions should be rendered
+* then, the domain service's top-level name (typically explicitly specified using xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_named[`named()`]) is used to determine the top-level menu item to be rendered on the menu bar
 * finally, if there is more than domain service that has the same name, then the `menuOrder` attribute is used to order those actions on the menu item drop-down.
 
 For example, the screenshot below shows the "prototyping" menu from the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp]:

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainServiceLayout_named.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainServiceLayout_named.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainServiceLayout_named.adoc
index 9ee9806..030b5b4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainServiceLayout_named.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainServiceLayout_named.adoc
@@ -5,12 +5,12 @@
 :_imagesdir: images/
 
 
-The `named()` attribute explicitly specifies the domain service's name, overriding the name that would normally be inferred from the Java source code.  This attribute can also be specified for xref:rgant.adoc#_rgant-ActionLayout_named[actions], xref:rgant.adoc#_rgant-CollectionLayout_named[collections], xref:rgant.adoc#_rgant-PropertyLayout_named[properties], xref:rgant.adoc#_rgant-ParameterLayout_named[parameters], xref:rgant.adoc#_rgant-DomainObjectLayout_named[domain objects] and xref:rgant.adoc#_rgant-ViewModelLayout_named[view models].
+The `named()` attribute explicitly specifies the domain service's name, overriding the name that would normally be inferred from the Java source code.  This attribute can also be specified for xref:../rgant/rgant.adoc#_rgant-ActionLayout_named[actions], xref:../rgant/rgant.adoc#_rgant-CollectionLayout_named[collections], xref:../rgant/rgant.adoc#_rgant-PropertyLayout_named[properties], xref:../rgant/rgant.adoc#_rgant-ParameterLayout_named[parameters], xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_named[domain objects] and xref:../rgant/rgant.adoc#_rgant-ViewModelLayout_named[view models].
 
 
 [TIP]
 ====
-The value of this attribute also has an important role to play in the positioning of the domain service's actions relative to the actions of other domain services.  See xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`menuOrder()`] for a full discussion with examples.
+The value of this attribute also has an important role to play in the positioning of the domain service's actions relative to the actions of other domain services.  See xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`menuOrder()`] for a full discussion with examples.
 ====
 
 For example:

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainService_nature.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainService_nature.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainService_nature.adoc
index bedafaf..d53ca76 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainService_nature.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainService_nature.adoc
@@ -21,7 +21,7 @@ The service's actions appear on menus and in the REST API, but are not contribut
 +
 The service's actions are intended only to be used as contributed actions/associations to domain objects and view models. +
 +
-The related xref:rgant.adoc#_rgant-ActionLayout_contributedAs[`@ActionLayout#contributedAs()`] determines whether any given (1-arg) action is contributed as an association rather than an action.
+The related xref:../rgant/rgant.adoc#_rgant-ActionLayout_contributedAs[`@ActionLayout#contributedAs()`] determines whether any given (1-arg) action is contributed as an association rather than an action.
 
 * `VIEW_REST_ONLY` +
 +
@@ -65,7 +65,7 @@ public class LoanRepository {                                  // <1>
 }
 ----
 <1> `Repository` as a suffix for a domain-layer service
-<2> methods on `DOMAIN` services are often xref:rgant.adoc#_rgant-Programmatic[`@Programmatic`]; they will never be exposed in the UI, so there's little point in including them in Apache Isis' metamodel
+<2> methods on `DOMAIN` services are often xref:../rgant/rgant.adoc#_rgant-Programmatic[`@Programmatic`]; they will never be exposed in the UI, so there's little point in including them in Apache Isis' metamodel
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainService_objectType.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainService_objectType.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainService_objectType.adoc
index 767c8a7..7ceca4d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainService_objectType.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainService_objectType.adoc
@@ -11,8 +11,8 @@ This value is used internally to generate a string representation of an service
 This can appear in several contexts, including:
 
 * as the value of `Bookmark#getObjectType()` and in the `toString()` value of `Bookmark`
- (see xref:rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`])
-* in the serialization of `OidDto` in the xref:rgcms.adoc#_rgcms_schema-cmd[command] and xref:rgcms.adoc#_rgcms_schema-ixn[interaction] schemas
+ (see xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`])
+* in the serialization of `OidDto` in the xref:../rgcms/rgcms.adoc#_rgcms_schema-cmd[command] and xref:../rgcms/rgcms.adoc#_rgcms_schema-ixn[interaction] schemas
 * in the URLs of the xref:ugvro.adoc#[RestfulObjects viewer]
 * in the URLs of the xref:ugvw.adoc#[Wicket viewer] (specifically, for bookmarked actions)
 
@@ -39,7 +39,7 @@ public class OrderMenu {
 The rules of precedence are:
 
 1. `@DomainService#objectType`
-2. xref:rgcms.adoc#_rgcms_methods_reserved_getId[`getId()`]
+2. xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_getId[`getId()`]
 3. The fully qualified class name.
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainService_repositoryFor.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainService_repositoryFor.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainService_repositoryFor.adoc
index 4656a01..6ac3782 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainService_repositoryFor.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainService_repositoryFor.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-The `repositoryFor()` attribute is intended for domain services (probably with a xref:rgant.adoc#_rgant-DomainService_nature[`nature=DOMAIN`]) that are intended to act as repositories for domain entities.
+The `repositoryFor()` attribute is intended for domain services (probably with a xref:../rgant/rgant.adoc#_rgant-DomainService_nature[`nature=DOMAIN`]) that are intended to act as repositories for domain entities.
 
 For example:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Inject.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Inject.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Inject.adoc
index 2aae64a..6ba109e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Inject.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Inject.adoc
@@ -10,7 +10,7 @@ Apache Isis automatically injects domain services into other domain services and
 
 [NOTE]
 ====
-One omission: Apache Isis (currently) does not inject services into `o.a.i.applib.spec.Specification` instances (as used by xref:rgant.adoc#_rgant-Property_mustSatisfy[`@Property#mustSatisfy()`] and xref:rgant.adoc#_rgant-Parameter_mustSatisfy[`@Parameter#mustSatisfy()`] annotations.
+One omission: Apache Isis (currently) does not inject services into `o.a.i.applib.spec.Specification` instances (as used by xref:../rgant/rgant.adoc#_rgant-Property_mustSatisfy[`@Property#mustSatisfy()`] and xref:../rgant/rgant.adoc#_rgant-Parameter_mustSatisfy[`@Parameter#mustSatisfy()`] annotations.
 ====
 
 Isis supports several syntaxes for injecting domain services.  The simplest uses the `@javax.inject.Inject` annotation on the field, as defined in link:https://jcp.org/en/jsr/detail?id=330[JSR-330].
@@ -27,7 +27,7 @@ public class Customer {
     OrderRepository orders;                    // <2>
 }
 ----
-<1> an alternative implementation would be to implement `findRecentOrders()` as a xref:ugfun.adoc#_ugfun_how-tos_contributed-members[contributed action].
+<1> an alternative implementation would be to implement `findRecentOrders()` as a xref:../ugfun/ugfun.adoc#_ugfun_how-tos_contributed-members[contributed action].
 <2> we recommend default (rather than `private`) visibility so that unit tests can easily mock out the service
 
 
@@ -94,7 +94,7 @@ public class Customer {
 
 [NOTE]
 ====
-An alternative and almost equivalent design would be to publish an event using the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] and implement the domain services as subscribers to
+An alternative and almost equivalent design would be to publish an event using the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] and implement the domain services as subscribers to
 the event.  This alternative design is used in the (non-ASF) http://github.com/isisaddons/isis-module-poly[Isis addons' poly] module, for example.
 ====
 
@@ -114,7 +114,7 @@ Customer cust = container.newTransientInstance(Customer.class);  <1>
 // initialize state of "cust"
 container.persist(cust);
 ----
-<1> where `container` is an instance of xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`].
+<1> where `container` is an instance of xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`].
 
 View models are created similarly:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-MemberGroupLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-MemberGroupLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-MemberGroupLayout.adoc
index 7ec4935..f9400a5 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-MemberGroupLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-MemberGroupLayout.adoc
@@ -6,10 +6,10 @@
 
 
 
-The `@MemberGroupLayout` annotation specifies how an object's properties and collections are grouped together into columns, also specifying the relative positioning of those columns.  It works in conjunction with the xref:rgant.adoc#_rgant-MemberOrder[`@MemberOrder`] annotation.
+The `@MemberGroupLayout` annotation specifies how an object's properties and collections are grouped together into columns, also specifying the relative positioning of those columns.  It works in conjunction with the xref:../rgant/rgant.adoc#_rgant-MemberOrder[`@MemberOrder`] annotation.
 
 
-The `@MemberOrder` annotation is used to specify the relative order of domain object members, that is: properties, collections and actions.  It works in conjunction with the xref:rgant.adoc#_rgant-MemberGroupLayout[`@MemberGroupLayout`] annotation.
+The `@MemberOrder` annotation is used to specify the relative order of domain object members, that is: properties, collections and actions.  It works in conjunction with the xref:../rgant/rgant.adoc#_rgant-MemberGroupLayout[`@MemberGroupLayout`] annotation.
 
 The annotation defines two attributes, `name()` and `sequence()`.  Broadly speaking the `name()` attribute is used to group or associate members together, while the `sequence()` attribute orders members once they have been grouped.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-MemberOrder.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-MemberOrder.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-MemberOrder.adoc
index 1aca506..c813ea4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-MemberOrder.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-MemberOrder.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-The `@MemberOrder` annotation is used to specify the relative order of domain object members, that is: properties, collections and actions.  It works in conjunction with the xref:rgant.adoc#_rgant-MemberGroupLayout[`@MemberGroupLayout`] annotation.
+The `@MemberOrder` annotation is used to specify the relative order of domain object members, that is: properties, collections and actions.  It works in conjunction with the xref:../rgant/rgant.adoc#_rgant-MemberGroupLayout[`@MemberGroupLayout`] annotation.
 
 The annotation defines four attributes:
 
@@ -27,8 +27,8 @@ As this is an important topic, there is a xref:ugvw.adoc#_ugvw_layout[separate c
 
 [TIP]
 ====
-The annotation is one of a handful (others including xref:rgant.adoc#_rgant-Collection[`@Collection`], xref:rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`], xref:rgant.adoc#_rgant-Property[`@Property`])
- and xref:rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`] that can also be applied to the field, rather than the getter method.  This is specifically
+The annotation is one of a handful (others including xref:../rgant/rgant.adoc#_rgant-Collection[`@Collection`], xref:../rgant/rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`], xref:../rgant/rgant.adoc#_rgant-Property[`@Property`])
+ and xref:../rgant/rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`] that can also be applied to the field, rather than the getter method.  This is specifically
 so that boilerplate-busting tools such as link:https://projectlombok.org/[Project Lombok] can be used.
 ====
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-MinLength.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-MinLength.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-MinLength.adoc
index 87fad10..d38ad65 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-MinLength.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-MinLength.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-The `@MinLength` annotation is used to specify the minimum number of characters in a search of an xref:rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`] supporting method.
+The `@MinLength` annotation is used to specify the minimum number of characters in a search of an xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`] supporting method.
 
 
 For example:

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Mixin.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Mixin.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Mixin.adoc
index 587868a..92b1acf 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Mixin.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Mixin.adoc
@@ -25,7 +25,7 @@ The table below summarizes the annotation's attributes.
 | Description
 
 
-|xref:rgant.adoc#_rgant-Mixin_method[`method()`]
+|xref:../rgant/rgant.adoc#_rgant-Mixin_method[`method()`]
 |Method name within the mixin
 |How to recognize the "reserved" method name, meaning that the mixin's own name will be inferred from the mixin type.
 Typical examples are "exec", "execute", "invoke", "apply" and so on.
@@ -34,7 +34,7 @@ The default "reserved" method name is `$$`.
 |===
 
 An alternative and equivalent approach is to use the
-xref:rgant.adoc#_rgant-DomainObject_nature[`@DomainObject#nature()`] annotation with a nature of `MIXIN`.
+xref:../rgant/rgant.adoc#_rgant-DomainObject_nature[`@DomainObject#nature()`] annotation with a nature of `MIXIN`.
 
 
 include::_rgant-Mixin_method.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Nullable.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Nullable.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Nullable.adoc
index 1186553..51c4cb0 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Nullable.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Nullable.adoc
@@ -34,20 +34,20 @@ public Customer updateName(@javax.annotation.Nullable final String name) {
 ----
 
 Apache Isis does provide several other ways to specify optionality: using the
-xref:rgant.adoc#_rgant_Property_optionality[`@Property#optionality()`] /
-xref:rgant.adoc#_rgant_Parameter_optionality[`@Parameter#optionality()`] annotation.  For properties, the optionality
-can also be inferred from the xref:rgant.adoc#_rgant_Column_allowsNull[`@Column#allowsNull()`] attribute.
+xref:../rgant/rgant.adoc#_rgant_Property_optionality[`@Property#optionality()`] /
+xref:../rgant/rgant.adoc#_rgant_Parameter_optionality[`@Parameter#optionality()`] annotation.  For properties, the optionality
+can also be inferred from the xref:../rgant/rgant.adoc#_rgant_Column_allowsNull[`@Column#allowsNull()`] attribute.
 
 [TIP]
 ====
 See the
-xref:rgant.adoc#_rgant_Property_optionality[`@Property#optionality()`] documentation for a much fuller discussion on
+xref:../rgant/rgant.adoc#_rgant_Property_optionality[`@Property#optionality()`] documentation for a much fuller discussion on
 the relationship between using the Apache Isis annotations vs
-xref:rgant.adoc#_rgant_Column_allowsNull[`@Column#allowsNull()`].
+xref:../rgant/rgant.adoc#_rgant_Column_allowsNull[`@Column#allowsNull()`].
 ====
 
 If more than one method is specified then the framework will validate that there are no incompatibilities (and fail to
-boot otherwise).  This can also be verified using the xref:rgmvn.adoc#_rgmvn_validate[validate goal] of the Apache
+boot otherwise).  This can also be verified using the xref:../rgmvn/rgmvn.adoc#_rgmvn_validate[validate goal] of the Apache
 Isis Maven plugin.
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Parameter.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Parameter.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Parameter.adoc
index 539ca23..9f2d280 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Parameter.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Parameter.adoc
@@ -18,38 +18,38 @@ The table below summarizes the annotation's attributes.
 | Description
 
 
-|xref:rgant.adoc#_rgant-Parameter_fileAccept[`fileAccept()`]
+|xref:../rgant/rgant.adoc#_rgant-Parameter_fileAccept[`fileAccept()`]
 |Media type or file extension
-|Hints the file type to be uploaded for xref:rgcms.adoc#_rgcms_classes_value-types_Blob[`Blob`]
- or xref:rgcms.adoc#_rgcms_classes_value-types_Clob[`Clob`]. +
+|Hints the file type to be uploaded for xref:../rgcms/rgcms.adoc#_rgcms_classes_value-types_Blob[`Blob`]
+ or xref:../rgcms/rgcms.adoc#_rgcms_classes_value-types_Clob[`Clob`]. +
  +
  Note that this does not prevent the user from uploading some other file type; rather it merely defaults the file type in the file open dialog.
 
 
 
-|xref:rgant.adoc#_rgant-Parameter_maxLength[`maxLength()`]
+|xref:../rgant/rgant.adoc#_rgant-Parameter_maxLength[`maxLength()`]
 |Positive integer
 |maximum number of characters for string parameters; ignored otherwise
 
 
 |`minLength()`
 |Positive integer
-|Deprecated; use xref:rgant.adoc#_rgant_minLength[`@MinLength`] instead. +
+|Deprecated; use xref:../rgant/rgant.adoc#_rgant_minLength[`@MinLength`] instead. +
 
-Can be used to specify the minimum length for xref:rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`] supporting method; but because this _is a_ supporting method rather than the action method itself, we now feel it is misleading to use the `@Parameter` annotation in this situation.
+Can be used to specify the minimum length for xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`] supporting method; but because this _is a_ supporting method rather than the action method itself, we now feel it is misleading to use the `@Parameter` annotation in this situation.
 
 
-|xref:rgant.adoc#_rgant-Parameter_mustSatisfy[`mustSatisfy()`]
+|xref:../rgant/rgant.adoc#_rgant-Parameter_mustSatisfy[`mustSatisfy()`]
 |implementation of `o.a.i.applib.spec.Specification`
 |allows arbitrary validation to be applied
 
 
-|xref:rgant.adoc#_rgant-Parameter_optionality[`optionality()`]
+|xref:../rgant/rgant.adoc#_rgant-Parameter_optionality[`optionality()`]
 |`MANDATORY`, `OPTIONAL` (`MANDATORY`)
 |specifies a parameter is optional rather than mandatory
 
 
-|xref:rgant.adoc#_rgant-Parameter_regexPattern[regexPattern()]
+|xref:../rgant/rgant.adoc#_rgant-Parameter_regexPattern[regexPattern()]
 |regular expression
 |validates the contents of a string parameter against the regular expression pattern
 

[06/58] [abbrv] isis git commit: ISIS-1521: fixes xref links between guides

[da...@apache.org]

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_LayoutService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_LayoutService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_LayoutService.adoc
index c164e0a..785354c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_LayoutService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_LayoutService.adoc
@@ -48,9 +48,9 @@ XML, and how much (if any) will be obtained elsewhere, typically from annotation
 |===
 
 | Style
-|xref:rgant.adoc#_rgant-MemberGroupLayout[`@MemberGroupLayout`]
-| xref:rgant.adoc#_rgant-MemberOrder[`@MemberOrder`]
-| xref:rgant.adoc#_rgant-ActionLayout[`@ActionLayout`], xref:rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`], xref:rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`]
+|xref:../rgant/rgant.adoc#_rgant-MemberGroupLayout[`@MemberGroupLayout`]
+| xref:../rgant/rgant.adoc#_rgant-MemberOrder[`@MemberOrder`]
+| xref:../rgant/rgant.adoc#_rgant-ActionLayout[`@ActionLayout`], xref:../rgant/rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`], xref:../rgant/rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`]
 
 
 |`COMPLETE`
@@ -88,7 +88,7 @@ As a developer, you therefore have a choice as to how you provide the metadata r
 
 The service's functionality is exposed in the UI through a mixin (per object) and a menu action (for all objects):
 
-* the xref:rgant.adoc#_rgcms_classes_mixins_Object[`Object` mixin] provides the ability to download the XML layout for
+* the xref:../rgant/rgant.adoc#_rgcms_classes_mixins_Object[`Object` mixin] provides the ability to download the XML layout for
 any domain object (entity or view model).
 
 * the `LayoutServiceMenu` provides the ability to download all XML layouts as a single ZIP file (in any of the
@@ -102,6 +102,6 @@ desired.
 [[__rgsvc_api_LayoutService_related-domain-services]]
 == Related Domain Services
 
-The xref:rgsvc.adoc#_rgsvc_spi_GridService[`GridService`] is responsible for loading and normalizing layout XML for
-a domain class.  It in turn uses the xref:rgsvc.adoc#_rgsvc_spi_GridLoaderService[`GridLoaderService`] and  xref:rgsvc.adoc#_rgsvc_spi_GridSystemService[`GridSystemService`]
+The xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_GridService[`GridService`] is responsible for loading and normalizing layout XML for
+a domain class.  It in turn uses the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_GridLoaderService[`GridLoaderService`] and  xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_GridSystemService[`GridSystemService`]
 services.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_MementoService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_MementoService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_MementoService.adoc
index 0facf78..15f5f60 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_MementoService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_MementoService.adoc
@@ -12,9 +12,9 @@ all of their backing state, moreover which is safe for use within a URL.  This u
 
 The service can also be used to create a memento of arbitrary objects, however this usage is also deprecated.  (Prior
 to `1.13.0` it was used internally by the core implementation of
-xref:rgsvc.adoc#_rgsvc_api_BackgroundService[`BackgroundService`] to capture the state of action invocations so that
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BackgroundService[`BackgroundService`] to capture the state of action invocations so that
 they can be executed by a background process; this is now done using
-xref:rgfis.adoc#_rgfis_spi_CommandDtoServiceInternal[`CommandDtoServiceInternal`]).
+xref:../rgfis/rgfis.adoc#_rgfis_spi_CommandDtoServiceInternal[`CommandDtoServiceInternal`]).
 
 
 [NOTE]
@@ -82,11 +82,11 @@ If using another implementation, the `canSet(...)` method can be used to check i
 
 == Usage
 
-As noted in the introduction, a common use case for this service is in the implementation of the xref:rgcms.adoc#_rgcms_classes_super_AbstractViewModel[`ViewModel`] interface.
+As noted in the introduction, a common use case for this service is in the implementation of the xref:../rgcms/rgcms.adoc#_rgcms_classes_super_AbstractViewModel[`ViewModel`] interface.
 
 [TIP]
 ====
-Rather than implementing `ViewModel`, it's usually easier to annotate your view models with xref:rgant.adoc#_rgant-ViewModel[`@ViewModel`] (or equivalently xref:rgant.adoc#_rgant-DomainObject_nature[`@DomainObject#nature=EXTERNAL_ENTITY`] or xref:rgant.adoc#_rgant-DomainObject_nature[`@DomainObject#nature=INMEMORY_ENTITY`].
+Rather than implementing `ViewModel`, it's usually easier to annotate your view models with xref:../rgant/rgant.adoc#_rgant-ViewModel[`@ViewModel`] (or equivalently xref:../rgant/rgant.adoc#_rgant-DomainObject_nature[`@DomainObject#nature=EXTERNAL_ENTITY`] or xref:../rgant/rgant.adoc#_rgant-DomainObject_nature[`@DomainObject#nature=INMEMORY_ENTITY`].
 ====
 
 For example, suppose you were implementing a view model that represents an external entity in a SOAP web service.  To access this service the view model needs to store (say) the hostname, port number and an id to the object.
@@ -125,11 +125,11 @@ public class ExternalEntity implements ViewModel {
 
 == Related Services
 
-(Prior to `1.13.0`), the memento service was used by the xref:rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`]
+(Prior to `1.13.0`), the memento service was used by the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`]
 service and also
-xref:rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[`BackgroundCommandService`]. These both use a memento to capture a
+xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[`BackgroundCommandService`]. These both use a memento to capture a
 representation of an action invocation.  This is now done using
-xref:rgfis.adoc#_rgfis_spi_CommandDtoServiceInternal[`CommandDtoServiceInternal`].
+xref:../rgfis/rgfis.adoc#_rgfis_spi_CommandDtoServiceInternal[`CommandDtoServiceInternal`].
 
 
 
@@ -137,10 +137,10 @@ xref:rgfis.adoc#_rgfis_spi_CommandDtoServiceInternal[`CommandDtoServiceInternal`
 == Registering the Service
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
 implementation of `MementoService` service is automatically registered and injected (it is annotated with
 `@DomainService`) so no further configuration is required.
 
 To use an alternative implementation, use
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
+xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+in the xref:../rgsvc/rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_MessageService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_MessageService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_MessageService.adoc
index eb57549..7cb42ff 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_MessageService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_MessageService.adoc
@@ -9,7 +9,7 @@ The `MessageService` allows domain objects to raise information, warning or erro
 
 [NOTE]
 ====
-The methods in this service replace similar methods (now deprecated) in xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`].
+The methods in this service replace similar methods (now deprecated) in xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`].
 ====
 
 
@@ -66,13 +66,13 @@ The core framework provides a default implementation of this service (`o.a.i.cor
 == Registering the Service
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
 implementation of `MessageService` service is automatically registered and injected (it is annotated with
 `@DomainService`) so no further configuration is required.
 
 To use an alternative implementation, use
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
+xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+in the xref:../rgsvc/rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_MetamodelService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_MetamodelService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_MetamodelService.adoc
index 7e5ea83..e493b09 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_MetamodelService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_MetamodelService.adoc
@@ -52,17 +52,17 @@ The framework provides a default implementation of this service, `o.a.i.c.m.serv
 == Registering the Service
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
 implementation of `MetamodelService` service is automatically registered and injected (it is annotated with
 `@DomainService`) so no further configuration is required.
 
 To use an alternative implementation, use
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
+xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+in the xref:../rgsvc/rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
 
 
 == Related Services
 
 The `MetaModelServiceMenu` provides a method to download all domain members as a CSV.  Internally
 this calls `MetaModelService#export()`.  Under the covers this uses the API provided by the
-xref:rgsvc.adoc#_rgsvc_api_ApplicationFeatureRepository[`ApplicationFeatureRepository`] domain service.
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ApplicationFeatureRepository[`ApplicationFeatureRepository`] domain service.

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_MetricsService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_MetricsService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_MetricsService.adoc
index 5ab1992..7161213 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_MetricsService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_MetricsService.adoc
@@ -9,7 +9,7 @@
 The `MetricsService` is a request-scoped domain service that hooks into the JDO/DataNucleus
 ObjectStore to provide a number of counters relating to numbers of object loaded, dirtied etc.
 
-The service is used by the xref:rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] domain service (to populate the DTO held by the `Interaction.Execution`) and also by the (internal) xref:rgfis.adoc#_rgfis_spi_PublishingServiceInternal[`PublishingServiceInternal`] domain service (to populate
+The service is used by the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] domain service (to populate the DTO held by the `Interaction.Execution`) and also by the (internal) xref:../rgfis/rgfis.adoc#_rgfis_spi_PublishingServiceInternal[`PublishingServiceInternal`] domain service (to populate
 the `PublishedObjects` class.
 
 
@@ -28,8 +28,8 @@ public interface MetricsService {
 ----
 <1> The number of objects that have, so far in this request, been loaded from the database. Corresponds to the number of times that `javax.jdo.listener.LoadLifecycleListener#postLoad(InstanceLifecycleEvent)` is fired.
 <2> The number of objects that have, so far in this request, been dirtied/will need updating in the database); a good measure of the footprint of the interaction.  Corresponds to the number of times that `javax.jdo.listener.DirtyLifecycleListener#preDirty(InstanceLifecycleEvent)` callback is fired.
-<3> The number of individual properties of objects that were modified; a good measure of the amount of work being done in the interaction.  Corresponds to the number of times that the xref:rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`]'s (or
-xref:rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditerService`]'s) `audit(...)` method will be called as the transaction
+<3> The number of individual properties of objects that were modified; a good measure of the amount of work being done in the interaction.  Corresponds to the number of times that the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`]'s (or
+xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditerService`]'s) `audit(...)` method will be called as the transaction
 completes.
 
 The framework provides a default implementation of this API, namely `o.a.i.c.r.s.metrics.MetricsServiceDefault`.
@@ -38,12 +38,12 @@ The framework provides a default implementation of this API, namely `o.a.i.c.r.s
 == Registering the Service
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' default
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' default
 implementation of `MetricsService` class is automatically registered (it is annotated with `@DomainService`)
 so no further configuration is required.
 
 
 == Related Services
 
-The xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] also captures the metrics gathered by the
+The xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] also captures the metrics gathered by the
 `MetricsService` and publishes them as part of the `PublishedObjects` class (part of its SPI).

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_QueryResultsCache.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_QueryResultsCache.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_QueryResultsCache.adoc
index 079a90f..b67c06f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_QueryResultsCache.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_QueryResultsCache.adoc
@@ -111,16 +111,16 @@ This refactoring will be worthwhile provided that enough of the orders being pro
 == Registering the Service
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
 implementation of `QueryResultsCache` service is automatically registered and injected (it is annotated with
 `@DomainService`) so no further configuration is required.
 
 To use an alternative implementation, use
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
+xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+in the xref:../rgsvc/rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
 
 
 
 == Related Services
 
-The xref:rgsvc.adoc#_rgsvc_api_Scratchpad[`Scratchpad`] service is also intended for actions that are called many times, allowing arbitrary information to be shared between them. Those methods could be called from some outer loop in domain code, or by the framework itself if the action invoked has the xref:rgant.adoc#_rgant-Action_invokeOn[`@Action#invokeOn()`] annotation attribute set to `OBJECT_AND_COLLECTION` or `COLLECTION_ONLY`.
\ No newline at end of file
+The xref:../rgsvc/rgsvc.adoc#_rgsvc_api_Scratchpad[`Scratchpad`] service is also intended for actions that are called many times, allowing arbitrary information to be shared between them. Those methods could be called from some outer loop in domain code, or by the framework itself if the action invoked has the xref:../rgant/rgant.adoc#_rgant-Action_invokeOn[`@Action#invokeOn()`] annotation attribute set to `OBJECT_AND_COLLECTION` or `COLLECTION_ONLY`.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_RepositoryService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_RepositoryService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_RepositoryService.adoc
index a6e7def..362cb88 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_RepositoryService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_RepositoryService.adoc
@@ -9,12 +9,12 @@ The `RepositoryService` collects together methods for creating, persisting and s
 
 You can use it during prototyping to write naive queries (find all rows, then filter using the Guava `Predicate` API, or you can use it to call JDO link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/query.html#named[named queries] using JDOQL.
 
-As an alternative, you could also use link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/jdoql_typesafe.html[JDO typesafe queries] through the xref:rgsvc.adoc#_rgsvc_api_IsisJdoSupport[`IsisJdoSupport`] service.
+As an alternative, you could also use link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/jdoql_typesafe.html[JDO typesafe queries] through the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_IsisJdoSupport[`IsisJdoSupport`] service.
 
 
 [NOTE]
 ====
-The methods in this service replace similar methods (now deprecated) in xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`].
+The methods in this service replace similar methods (now deprecated) in xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`].
 ====
 
 
@@ -47,7 +47,7 @@ public interface RepositoryService {
 }
 ----
 <1> create a new non-persisted domain entity.  This is identical to
-xref:rgsvc.adoc#_rgsvc_api_FactoryService[`FactoryService`]'s `instantiate(...)` method, but is provided in the
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_FactoryService[`FactoryService`]'s `instantiate(...)` method, but is provided in the
 ``RepositoryService``'s API too because instantiating and persisting objects are often done together.
 <2> test whether a particular domain object is persistent or not
 <3> persist (ie save) an object to the persistent object store (or do nothing if it is already persistent).
@@ -83,7 +83,7 @@ repositoryService.persist(cust);
 
 You should be aware that by default Apache Isis queues up calls to `#persist()` and `#remove()`.  These are then executed either when the request completes (and the transaction commits), or if the queue is flushed.  This can be done either implicitly by the framework, or as the result of a direct call to `#flush()`.
 
-By default the framework itself will cause `#flush()` to be called whenever a query is executed by way of `#allMatches(Query)`, as documented xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer_generic-repository-api[above].  However, this behaviour can be disabled using the  xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.services.container.disableAutoFlush`.
+By default the framework itself will cause `#flush()` to be called whenever a query is executed by way of `#allMatches(Query)`, as documented xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer_generic-repository-api[above].  However, this behaviour can be disabled using the  xref:../rgcfg/rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.services.container.disableAutoFlush`.
 
 
 
@@ -219,7 +219,7 @@ With respect to the other query APIs, the varargs parameters are optional, but a
 
 [TIP]
 ====
-It is also possible to query using DataNucleus' type-safe query API.  For more details, see xref:rgsvc.adoc#_rgsvc_api_IsisJdoSupport[`IsisJdoSupport`].
+It is also possible to query using DataNucleus' type-safe query API.  For more details, see xref:../rgsvc/rgsvc.adoc#_rgsvc_api_IsisJdoSupport[`IsisJdoSupport`].
 ====
 
 
@@ -255,17 +255,17 @@ This key allows this behaviour to be disabled.
 == Registering the Service
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
 implementation of `RepositoryService` service is automatically registered and injected (it is annotated with
 `@DomainService`) so no further configuration is required.
 
 To use an alternative implementation, use
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
+xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+in the xref:../rgsvc/rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
 
 
 
 == Related Services
 
-the xref:rgsvc.adoc#_rgsvc_api_FactoryService[`FactoryService`] is often used in conjunction with the `RepositoryService`, to instantiate domain objects before persisting.
+the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_FactoryService[`FactoryService`] is often used in conjunction with the `RepositoryService`, to instantiate domain objects before persisting.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_Scratchpad.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_Scratchpad.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_Scratchpad.adoc
index 3c7f3df..d6e09d9 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_Scratchpad.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_Scratchpad.adoc
@@ -36,7 +36,7 @@ This class (`o.a.i.applib.services.scratchpad.Scratchpad`) is also the implement
 
 == Usage
 
-The most common use-case is for xref:rgant.adoc#_rgant-Action_invokeOn[bulk] actions that act upon multiple objects in a list.  The (same) `Scratchpad` service is injected into each of these objects, and so they can use pass information.
+The most common use-case is for xref:../rgant/rgant.adoc#_rgant-Action_invokeOn[bulk] actions that act upon multiple objects in a list.  The (same) `Scratchpad` service is injected into each of these objects, and so they can use pass information.
 
 For example, the Isis addons example https://github.com/isisaddons/isis-app-todoapp/[todoapp] (not ASF) demonstrates how the `Scratchpad` service can be used to calculate the total cost of the selected `ToDoItem`s:
 
@@ -109,13 +109,13 @@ If using the xref:ugvw.adoc#[Wicket viewer], the `ToDoItemBulkUpdate` view model
 == Registering the Service
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
 implementation of `Scratchpad` service is automatically registered and injected (it is annotated with `@DomainService`)
 so no further configuration is required.
 
 To use an alternative implementation, use
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
+xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+in the xref:../rgsvc/rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
 
 
 
@@ -123,6 +123,6 @@ in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to th
 
 == Related Services
 
-The xref:rgsvc.adoc#_rgsvc_api_ActionInteractionContext[`ActionInteractionContext`] service allows xref:rgant.adoc#_rgant-Action_invokeOn[bulk actions] to co-ordinate with each other.
+The xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ActionInteractionContext[`ActionInteractionContext`] service allows xref:../rgant/rgant.adoc#_rgant-Action_invokeOn[bulk actions] to co-ordinate with each other.
 
-The xref:rgsvc.adoc#_rgsvc_api_QueryResultsCache[`QueryResultsCache`] is useful for caching the results of expensive method calls.
+The xref:../rgsvc/rgsvc.adoc#_rgsvc_api_QueryResultsCache[`QueryResultsCache`] is useful for caching the results of expensive method calls.

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_ServiceRegistry.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_ServiceRegistry.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_ServiceRegistry.adoc
index eebb5d0..63e1e65 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_ServiceRegistry.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_ServiceRegistry.adoc
@@ -9,7 +9,7 @@ The `ServiceRegistry2` service collects together methods for accessing other dom
 
 [NOTE]
 ====
-The methods in this service replace similar methods (now deprecated) in xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`].
+The methods in this service replace similar methods (now deprecated) in xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`].
 ====
 
 
@@ -32,7 +32,7 @@ public interface ServiceRegistry2 {
 <4> returns the list of all domain services that constitute the running application (including internal domain services).
 
 Service injection is done automatically if objects are created using the
-xref:rgsvc.adoc#_rgsvc_api_FactoryService[`FactoryService`].
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_FactoryService[`FactoryService`].
 
 
 
@@ -50,7 +50,7 @@ cust.setLastName("Mercury");
 repositoryService.persist(cust);
 ----
 
-The alternative is to use the xref:rgsvc.adoc#_rgsvc_api_FactoryService[`FactoryService`] API which performs both steps in a single factory method.
+The alternative is to use the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_FactoryService[`FactoryService`] API which performs both steps in a single factory method.
 
 
 
@@ -64,12 +64,12 @@ The core framework provides a default implementation of this service (`o.a.i.cor
 == Registering the Service
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
 implementation of `ServiceRegistry` service is automatically registered and injected (it is annotated with
 `@DomainService`) so no further configuration is required.
 
 To use an alternative implementation, use
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
+xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+in the xref:../rgsvc/rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_SessionManagementService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_SessionManagementService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_SessionManagementService.adoc
index fc96db5..1bbaa4d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_SessionManagementService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_SessionManagementService.adoc
@@ -47,10 +47,10 @@ The core framework provides a default implementation of this service (`o.a.i.cor
 == Registering the Service
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
 implementation of `SessionManagementService` service is automatically registered and injected (it is annotated with
 `@DomainService`) so no further configuration is required.
 
 To use an alternative implementation, use
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
+xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+in the xref:../rgsvc/rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_SudoService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_SudoService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_SudoService.adoc
index f060ce3..d07b8c3 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_SudoService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_SudoService.adoc
@@ -6,7 +6,7 @@
 
 
 
-The `SudoService` allows the current user reported by the xref:rgsvc.adoc#_rgsvc_api_UserService[`UserService`]  to be temporarily changed to some other user.
+The `SudoService` allows the current user reported by the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_UserService[`UserService`]  to be temporarily changed to some other user.
 This is useful both for xref:ugtst.adoc#_ugtst_integ-test-support[integration testing] (eg if testing a workflow system whereby objects are moved from one user to another) and while running xref:ugtst.adoc#_ugtst_fixture-scripts[fixture scripts] (eg setting up objects that would normally require several users to have acted upon the objects).
 
 
@@ -32,12 +32,12 @@ which will run the provided block of code (a `Runnable` or a `Callable`) in a wa
 `UserService#getUser()` will return the specified user (and roles, if specified).
 (If roles are not specified, then the roles of the current user are preserved).
 
-The current user/role reported by the internal xref:rgfis.adoc#_rgfis_spi_AuthenticationSessionProvider[`AuthenticationSessionProvider`] will also return the specified user/roles.
+The current user/role reported by the internal xref:../rgfis/rgfis.adoc#_rgfis_spi_AuthenticationSessionProvider[`AuthenticationSessionProvider`] will also return the specified user/roles.
 
 [IMPORTANT]
 ====
 Note however that this the "effective user" does not propagate through to the xref:ugsec.adoc#[Shiro security mechanism], which will continue to be evaluated according to the permissions of the current user.
-See the xref:rgsvc.adoc#__rgsvc_api_SudoService_ACCESS-ALL-ROLE[`ACCESS-ALL-ROLE`] below for details of how to circumvent this.
+See the xref:../rgsvc/rgsvc.adoc#__rgsvc_api_SudoService_ACCESS-ALL-ROLE[`ACCESS-ALL-ROLE`] below for details of how to circumvent this.
 ====
 
 
@@ -70,11 +70,11 @@ protected void execute(final ExecutionContext ec) {
 [[__rgsvc_api_SudoService_ACCESS-ALL-ROLE]]
 === ACCESS_ALL_ROLE
 
-When `sudo(...)` is called the "effective user" is reported by both xref:rgsvc.adoc#_rgsvc_api_UserService[`UserService`] and by xref:rgfis.adoc#_rgfis_spi_AuthenticationSessionProvider[`AuthenticationSessionProvider`], but does not propagate through to the xref:ugsec.adoc#[Shiro security mechanism].
+When `sudo(...)` is called the "effective user" is reported by both xref:../rgsvc/rgsvc.adoc#_rgsvc_api_UserService[`UserService`] and by xref:../rgfis/rgfis.adoc#_rgfis_spi_AuthenticationSessionProvider[`AuthenticationSessionProvider`], but does not propagate through to the xref:ugsec.adoc#[Shiro security mechanism].
 These continue to be evaluated according to the permissions of the current user.
 
 This can be a problem in certain use cases.
-For example if running a fixture script (which uses the xref:rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`]) from within an implementation of xref:rgsvc.adoc#_rgsvc_spi_UserRegistrationService[`UserRegistrationService`], this is likely to result in ``HiddenException``s being thrown because there is no effective user.
+For example if running a fixture script (which uses the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`]) from within an implementation of xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UserRegistrationService[`UserRegistrationService`], this is likely to result in ``HiddenException``s being thrown because there is no effective user.
 
 In such cases, permission checking can simply be disabled by specifying `SudoService.ACCESS_ALL_ROLE` as one of the roles.
 For example:
@@ -105,7 +105,7 @@ In the future this service may be used more deeply, eg to propagate permissions
 == SPI
 
 The `SudoService.Spi` service allows implementations of `SudoService` to notify other services/components that the effective user and roles are different.
-The default implementation of xref:rgsvc.adoc#_rgsvc_api_UserService[`UserService`] has been refactored to leverage this SPI.
+The default implementation of xref:../rgsvc/rgsvc.adoc#_rgsvc_api_UserService[`UserService`] has been refactored to leverage this SPI.
 
 [source,java]
 ----
@@ -128,10 +128,10 @@ The names of these methods were chosen based on link:href:https://shiro.apache.o
 == Registering the Service
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
 implementation of `SudoService` service is automatically registered and injected (it is annotated with
 `@DomainService`) so no further configuration is required.
 
 To use an alternative implementation, use
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
+xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+in the xref:../rgsvc/rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_SwaggerService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_SwaggerService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_SwaggerService.adoc
index ea6f21c..f16f083 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_SwaggerService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_SwaggerService.adoc
@@ -38,9 +38,9 @@ public interface SwaggerService {
 }
 ----
 <1> Generate a Swagger spec for use by third-party clients, ie public use.  This specification is restricted only to
-xref:ugbtb.adoc#_ugbtb_view-models[view model]s and to domain services with a xref:rgant.adoc#_rgant-DomainService_nature[nature] of `VIEW_REST_ONLY`.
+xref:ugbtb.adoc#_ugbtb_view-models[view model]s and to domain services with a xref:../rgant/rgant.adoc#_rgant-DomainService_nature[nature] of `VIEW_REST_ONLY`.
 <2> Generate a Swagger spec for use only by internally-managed clients, ie private internal use.  This specification includes domain entities and all menu domain services (as well as any view models).
-<3> Generate a Swagger spec that is the same as private case (above), but also including any xref:rgant.adoc#_rgant-Action_restrictTo[prototype] actions.
+<3> Generate a Swagger spec that is the same as private case (above), but also including any xref:../rgant/rgant.adoc#_rgant-Action_restrictTo[prototype] actions.
 <4> Swagger specs can be written either in JSON or YAML format.
 
 Isis provides a default implementation of the service, `o.a.i.core.metamodel.services.swagger.SwaggerServiceDefault`.
@@ -56,7 +56,7 @@ This service is provided as a convenience for applications, it is not (currently
 == Registering the Service
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
 implementation of `SwaggerService` service is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
 
 
@@ -64,6 +64,6 @@ implementation of `SwaggerService` service is automatically registered and injec
 
 A `SwaggerServiceMenu` domain service provides a prototype action that enables the swagger spec to be downloaded from the Wicket viewer's UI.
 
-Apache Isis' xref:rgmvn.aod[Maven plugin] also provides a xref:rgmvn.adoc#_rgmvn_swagger[swagger goal] which allows the spec file(s) to be generated at build time.  this then allows client-side stubs can then be generated in turn as part of a build pipeline.
+Apache Isis' xref:rgmvn.aod[Maven plugin] also provides a xref:../rgmvn/rgmvn.adoc#_rgmvn_swagger[swagger goal] which allows the spec file(s) to be generated at build time.  this then allows client-side stubs can then be generated in turn as part of a build pipeline.
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_SwitchUserService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_SwitchUserService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_SwitchUserService.adoc
index 52de8a7..60d6de6 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_SwitchUserService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_SwitchUserService.adoc
@@ -14,7 +14,7 @@ different users of the system.
 [NOTE]
 ====
 This service is deprecated; use xref:ugtst.adoc#_ugtst_fixture-scripts[fixture scripts] and the
-xref:rgsvc.adoc#_rgsvc_api_SudoService[`SudoService`] instead.
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_SudoService[`SudoService`] instead.
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_TitleService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_TitleService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_TitleService.adoc
index 6960a88..0919d5b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_TitleService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_TitleService.adoc
@@ -9,7 +9,7 @@ The `TitleService` provides methods to programmatically obtain the title and ico
 
 [NOTE]
 ====
-The methods in this service replace similar methods (now deprecated) in xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`].
+The methods in this service replace similar methods (now deprecated) in xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`].
 ====
 
 
@@ -63,12 +63,12 @@ The core framework provides a default implementation of this service (`o.a.i.cor
 == Registering the Service
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
 implementation of `TitleService` service is automatically registered and injected (it is annotated with
 `@DomainService`) so no further configuration is required.
 
 To use an alternative implementation, use
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
+xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+in the xref:../rgsvc/rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_TransactionService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_TransactionService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_TransactionService.adoc
index 09f03a4..9dca04d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_TransactionService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_TransactionService.adoc
@@ -9,7 +9,7 @@ The `TransactionService` provides a small number of methods to allow domain obje
 
 [NOTE]
 ====
-The methods in this service replace similar methods (now deprecated) in xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`].
+The methods in this service replace similar methods (now deprecated) in xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`].
 ====
 
 
@@ -31,7 +31,7 @@ and will commit that transaction after the interaction has completed.  Under cer
 perform data migration, say, or for large fixture scripts), it can be helpful to programmatically complete one
 transaction and start another one.
 <3> If the user interaction creates/persists an object or deletes an object (eg using the
-xref:rgsvc.adoc#_rgsvc_api_RepositoryService[`RepositoryService`]'s `persist()` or `delete()` methods), then the
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_RepositoryService[`RepositoryService`]'s `persist()` or `delete()` methods), then the
 framework actually queues up the work and only performs the persistence command either at the end of the transaction
 or immediately prior to the next query.  Performing a flush will cause any pending calls to be performed immediately.
 
@@ -51,7 +51,7 @@ public interface Transaction {
 }
 ----
 <1> is a unique identifier for the interaction/request, as defined by the
-xref:rgcms.adoc#_rgcms_classes_mixins_HasTransactionId[`HasTransactionId`] mixin.
+xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins_HasTransactionId[`HasTransactionId`] mixin.
 <2> there can actually be multiple transactions within such a request/interaction; the sequence is a (0-based) is used
 to distinguish such.
 <3> as per `TransactionService#flushTransaction()` described above.
@@ -88,10 +88,10 @@ The core framework provides a default implementation of this service (`o.a.i.cor
 == Registering the Service
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
 implementation of `TransactionService` service is automatically registered and injected (it is annotated with
 `@DomainService`) so no further configuration is required.
 
 To use an alternative implementation, use
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
+xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+in the xref:../rgsvc/rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_UserService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_UserService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_UserService.adoc
index d07f38b..bca048e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_UserService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_UserService.adoc
@@ -7,12 +7,12 @@
 
 The `UserService` allows the domain object to obtain the identity of the user interacting with said object.
 
-If xref:rgsvc.adoc#_rgsvc_api_SudoService[`SudoService`] has been used to temporarily override the user and/or roles, then this service will report the overridden values instead.
+If xref:../rgsvc/rgsvc.adoc#_rgsvc_api_SudoService[`SudoService`] has been used to temporarily override the user and/or roles, then this service will report the overridden values instead.
 
 
 [NOTE]
 ====
-The methods in this service replace similar methods (now deprecated) in xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`].
+The methods in this service replace similar methods (now deprecated) in xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`].
 ====
 
 
@@ -73,13 +73,13 @@ The core framework provides a default implementation of this service (`o.a.i.cor
 == Registering the Service
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
 implementation of `UserService` service is automatically registered and injected (it is annotated with
 `@DomainService`) so no further configuration is required.
 
 To use an alternative implementation, use
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
+xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+in the xref:../rgsvc/rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_WrapperFactory.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_WrapperFactory.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_WrapperFactory.adoc
index 415989e..5eaa6b1 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_WrapperFactory.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_WrapperFactory.adoc
@@ -56,8 +56,8 @@ public interface WrapperFactory {
 <3> whether the supplied object has been wrapped.
 <4> enumerates how the wrapper interacts with the underlying domain object.
 <5> validate all business rules and then execute.
-<6> skip all business rules and then execute (including creating xref:rgant.adoc#_rgant-Action_command[command]s and firing pre- and post-execute xref:rgant.adoc#_rgant-Action_domainEvent[domain event]s).
-<7> validate all business rules (including those from xref:rgant.adoc#_rgant-Action_domainEvent[domain event]s) but do not execute.
+<6> skip all business rules and then execute (including creating xref:../rgant/rgant.adoc#_rgant-Action_command[command]s and firing pre- and post-execute xref:../rgant/rgant.adoc#_rgant-Action_domainEvent[domain event]s).
+<7> validate all business rules (including those from xref:../rgant/rgant.adoc#_rgant-Action_domainEvent[domain event]s) but do not execute.
 <8> convenience method to invoke `wrap(...)` with `ExecuteMode#NO_EXECUTE` (make this feature more discoverable)
 <9> convenience method to invoke `wrap(...)` with `ExecuteMode#SKIP_RULES` (make this feature more discoverable)
 
@@ -74,8 +74,8 @@ Calling any of the above methods may result in a (subclass of) `InteractionExcep
 
 In addition, the following methods may also be called:
 
-* the xref:rgcms.adoc#_rgcms_methods_reserved_title[`title()`] and `toString()` methods
-* any xref:rgcms.adoc#_rgcms_methods_prefixes_default[`default...()`], xref:rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`] or xref:rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`] methods
+* the xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_title[`title()`] and `toString()` methods
+* any xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_default[`default...()`], xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`] or xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`] methods
 
 An exception will be thrown if any other methods are thrown.
 
@@ -114,7 +114,7 @@ public class CustomerAgent {
 
 [NOTE]
 ====
-It ought to be possible to implement an xref:rgsvc.adoc#_rgsvc_spi_ExceptionRecognizer[`ExceptionRecognizer`]s that would allow the above boilerplate to be removed.  This recognizer service would recognize the `InteractionException` and convert to a suitable message.
+It ought to be possible to implement an xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ExceptionRecognizer[`ExceptionRecognizer`]s that would allow the above boilerplate to be removed.  This recognizer service would recognize the `InteractionException` and convert to a suitable message.
 
 At the time of writing Apache Isis does not provide an out-of-the-box implementation of such an `ExceptionRecognizer`; but it should be simple enough to write one\u2026
 ====
@@ -153,10 +153,10 @@ The original intent of this API was to enable test transcripts to be captured (i
 == Registering the Service
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
 implementation of `WrapperFactory` service is automatically registered and injected (it is annotated with
 `@DomainService`) so no further configuration is required.
 
 To use an alternative implementation, use
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
+xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+in the xref:../rgsvc/rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_XmlSnapshotService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_XmlSnapshotService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_XmlSnapshotService.adoc
index 250681d..6090bcd 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_XmlSnapshotService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_XmlSnapshotService.adoc
@@ -194,25 +194,25 @@ public interface XmlSnapshotService {
 == Registering the Service
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
 implementation of `XmlSnapshotService` service is automatically registered and injected (it is annotated with
 `@DomainService`) so no further configuration is required.
 
 To use an alternative implementation, use
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
+xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+in the xref:../rgsvc/rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
 
 
 
 == Related Services
 
-The xref:rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`] provides a mechanism for obtaining a string representations of a single domain object.
+The xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`] provides a mechanism for obtaining a string representations of a single domain object.
 
-The xref:rgsvc.adoc#_rgsvc_api_MementoService[`MementoService`] also provides a mechanism for generating string representations of domain objects.
+The xref:../rgsvc/rgsvc.adoc#_rgsvc_api_MementoService[`MementoService`] also provides a mechanism for generating string representations of domain objects.
 
-The xref:rgsvc.adoc#_rgsvc_api_JaxbService[`JaxbService`] is a simple wrapper around
+The xref:../rgsvc/rgsvc.adoc#_rgsvc_api_JaxbService[`JaxbService`] is a simple wrapper around
 standard JAXB functionality for generating both XMLs and XSDs from JAXB-annotated classes.  Note that there is built-in support for JAXB classes (ie annotated with
-xref:rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`]) to be used as view models.
+xref:../rgant/rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`]) to be used as view models.
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_application-layer-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_application-layer-api.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_application-layer-api.adoc
index 3ca4ce6..692cd3e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_application-layer-api.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_application-layer-api.adoc
@@ -20,7 +20,7 @@ The table below summarizes the application layer APIs defined by Apache Isis.  I
 |Implementation
 |Notes
 
-|xref:rgsvc.adoc#_rgsvc_api_AcceptHeaderService[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_api_AcceptHeaderService[`o.a.i.applib.` +
 `services.acceptheader` +
 `AcceptHeaderService`]
 |Request-scoped access to HTTP Accept headers.
@@ -30,7 +30,7 @@ The table below summarizes the application layer APIs defined by Apache Isis.  I
 |Populated only when the domain objects are accessed using the xref:ugvro.adoc#[Restful Objects viewer].
 
 
-|xref:rgsvc.adoc#_rgsvc_api_ActionInvocationContext[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ActionInvocationContext[`o.a.i.applib.` +
 `services.actinv` +
 `ActionInvocation-` +
 `Context`]
@@ -42,7 +42,7 @@ The table below summarizes the application layer APIs defined by Apache Isis.  I
 
 
 
-|xref:rgsvc.adoc#_rgsvc_api_BackgroundService[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BackgroundService[`o.a.i.applib.` +
 `services.background` +
 `BackgroundService`]
 |Programmatic persistence of commands to be persisted (so can be executed by a background mechanism, eg scheduler)
@@ -50,10 +50,10 @@ The table below summarizes the application layer APIs defined by Apache Isis.  I
 ``o.a.i.core`` +
 ``isis-core-runtime``
 |depends on: +
-xref:rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[`BackgroundCommand-Service`]
+xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[`BackgroundCommand-Service`]
 
 
-|xref:rgsvc.adoc#_rgsvc_api_CommandContext[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_api_CommandContext[`o.a.i.applib.` +
 `services.command` +
 `CommandContext`]
 |Request-scoped access to capture the users's __intention__ to invoke an action or to edit a property.
@@ -62,12 +62,12 @@ xref:rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[`BackgroundCommand-Service`]
 ``isis-core-applib``
 |API is also a concrete class. +
 depends on: +
-xref:rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] for persistent `Command`, else in-memory impl. used.
+xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] for persistent `Command`, else in-memory impl. used.
 
-The xref:rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] manages the actual execution of the command.
+The xref:../rgsvc/rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] manages the actual execution of the command.
 
 
-|xref:rgsvc.adoc#_rgsvc_api_InteractionContext[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_api_InteractionContext[`o.a.i.applib.` +
 `services.iactn` +
 `InteractionContext`]
 |Request-scoped access to the current member execution (action invocation or property edit),
@@ -79,7 +79,7 @@ represented as the `Interaction` context.
 
 
 
-|xref:rgsvc.adoc#_rgsvc_api_MessageService[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_api_MessageService[`o.a.i.applib.` +
 `services.message` +
 `MessageService`]
 |Methods to inform or warn the user, or to raise errors.
@@ -87,10 +87,10 @@ represented as the `Interaction` context.
 ``Default`` +
 ``o.a.i.core`` +
 ``isis-core-metamodel``
-|Supercedes methods in xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`].
+|Supercedes methods in xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`].
 
 
-|xref:rgsvc.adoc#_rgsvc_api_SessionManagementService[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_api_SessionManagementService[`o.a.i.applib.` +
 `services.sessmgmt` +
 `SessionManagementService`]
 |Methods for batching long-running work (eg data migration) into multiple sessions.
@@ -101,7 +101,7 @@ represented as the `Interaction` context.
 |
 
 
-|xref:rgsvc.adoc#_rgsvc_api_TitleService[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_api_TitleService[`o.a.i.applib.` +
 `services.title` +
 `TitleService`]
 |Methods to programmatically obtain the title or icon of a domain object.
@@ -109,11 +109,11 @@ represented as the `Interaction` context.
 ``Default`` +
 ``o.a.i.core`` +
 ``isis-core-metamodel``
-|Supercedes methods in xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`].
+|Supercedes methods in xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`].
 
 
 
-|xref:rgsvc.adoc#_rgsvc_api_TransactionService[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_api_TransactionService[`o.a.i.applib.` +
 `services.xactn` +
 `TransactionService`]
 |Methods for managing transactions.
@@ -121,11 +121,11 @@ represented as the `Interaction` context.
 ``Default`` +
 ``o.a.i.core`` +
 ``isis-core-metamodel``
-|Supercedes methods in xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`].
+|Supercedes methods in xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`].
 
 
 
-|xref:rgsvc.adoc#_rgsvc_api_WrapperFactory[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_api_WrapperFactory[`o.a.i.applib.` +
 `services.wrapper` +
 `WrapperFactory`]
 |Interact with another domain object "as if" through the UI (enforcing business rules, firing domain events)

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_application-layer-spi.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_application-layer-spi.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_application-layer-spi.adoc
index c49568e..66a9cce 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_application-layer-spi.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_application-layer-spi.adoc
@@ -20,7 +20,7 @@ The table below summarizes the application layer SPIs defined by Apache Isis.  I
 |Notes
 
 
-|xref:rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[`o.a.i.applib.` +
 `services.background` +
 `BackgroundCommandService`]
 |Persisted a memento of an action invocation such that it can be executed asynchronously ("in the background") eg by a scheduler.
@@ -35,7 +35,7 @@ The table below summarizes the application layer SPIs defined by Apache Isis.  I
 
 
 
-|xref:rgsvc.adoc#_rgsvc_spi_CommandService[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_CommandService[`o.a.i.applib.` +
 `services.command.spi` +
 `CommandService`]
 |Service to act as a factory and repository (create and save) of command instances, ie representations of an action invocation.  Used for command/auditing and background services.
@@ -49,7 +49,7 @@ The table below summarizes the application layer SPIs defined by Apache Isis.  I
 `JdoRepository`
 
 
-|xref:rgsvc.adoc#_rgsvc_api_HomePageProviderService[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_api_HomePageProviderService[`o.a.i.applib.` +
 `services.homepage` +
 `HomePageProviderService`]
 |Returns the home page object, if any is defined.
@@ -57,7 +57,7 @@ The table below summarizes the application layer SPIs defined by Apache Isis.  I
 `ServiceDefault` +
 ``o.a.i.core`` +
 ``isis-core-runtime``
-|Used by the default implementation of xref:rgsvc.adoc#_rgsvc_spi_RoutingService[`RoutingService`].
+|Used by the default implementation of xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_RoutingService[`RoutingService`].
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_bootstrapping-spi.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_bootstrapping-spi.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_bootstrapping-spi.adoc
index af2e242..d0f0499 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_bootstrapping-spi.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_bootstrapping-spi.adoc
@@ -20,12 +20,12 @@ The table below summarizes the bootstrapping SPI defined by Apache Isis.  It als
 |Notes
 
 
-|xref:rgsvc.adoc#_rgsvc_spi_ClassDiscoveryService[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ClassDiscoveryService[`o.a.i.applib.` +
 `services.classdiscovery` +
 `ClassDiscoveryService`]
-|Mechanism to locate (from the classpath) classes with a specific annotation (eg xref:rgant.adoc#_rgant-DomainService[`@DomainService`])
+|Mechanism to locate (from the classpath) classes with a specific annotation (eg xref:../rgant/rgant.adoc#_rgant-DomainService[`@DomainService`])
 
-Subtypes of a given type (eg xref:rgcms.adoc#_rgcms_classes_super_FixtureScript[`FixtureScript`]).
+Subtypes of a given type (eg xref:../rgcms/rgcms.adoc#_rgcms_classes_super_FixtureScript[`FixtureScript`]).
 |`ClassDiscoveryService-` +
 `UsingReflections` +
 ``o.a.i.core`` +

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api.adoc
index c2ac39f..f06ba8b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_core-domain-api.adoc
@@ -22,7 +22,7 @@ The table below summarizes the core/domain APIs defined by Apache Isis.  It also
 
 
 
-|xref:rgsvc.adoc#_rgsvc_api_ClockService[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ClockService[`o.a.i.applib.` +
 `services.clock` +
 `ClockService`]
 |Access the current time (and for testing, allow the time to be changed)
@@ -33,7 +33,7 @@ The table below summarizes the core/domain APIs defined by Apache Isis.  It also
 
 
 
-|xref:rgsvc.adoc#_rgsvc_api_ConfigurationService[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ConfigurationService[`o.a.i.applib.` +
 `services.config` +
 `ConfigurationService`]
 |Access configuration properties (eg from `isis.properties` file)
@@ -43,10 +43,10 @@ The table below summarizes the core/domain APIs defined by Apache Isis.  It also
 ``isis-core-runtime``
 |The ``ConfigurationServiceMenu`` exposes the ``allConfigurationProperties`` action in the user interface. +
 +
-Supercedes methods in xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`].
+Supercedes methods in xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`].
 
 
-|xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`o.a.i.applib` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`o.a.i.applib` +
 `DomainObjectContainer`]
 |Miscellaneous functions, eg obtain title of object.
 |`DomainObjectContainer-` +
@@ -56,20 +56,20 @@ Supercedes methods in xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainOb
 |
 
 
-|xref:rgsvc.adoc#_rgsvc_api_EventBusService[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`o.a.i.applib.` +
 `services.eventbus` +
 `EventBusService`]
 |Programmatically post events to the internal event bus.  Also used by Apache Isis itself to broadcast domain events:
 
-* xref:rgant.adoc#_rgant-Action_domainEvent[`Action#domainEvent()`]
-* xref:rgant.adoc#_rgant-Property_domainEvent[`Property#domainEvent()`]
-* xref:rgant.adoc#_rgant-Collection_domainEvent[`Collection#domainEvent()`]
+* xref:../rgant/rgant.adoc#_rgant-Action_domainEvent[`Action#domainEvent()`]
+* xref:../rgant/rgant.adoc#_rgant-Property_domainEvent[`Property#domainEvent()`]
+* xref:../rgant/rgant.adoc#_rgant-Collection_domainEvent[`Collection#domainEvent()`]
 |`EventBusServiceJdo` +
 ``o.a.i.core`` +
 ``isis-core-runtime``
 |
 
-|xref:rgsvc.adoc#_rgsvc_api_FactoryService[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_api_FactoryService[`o.a.i.applib.` +
 `services.factory` +
 `FactoryService`]
 |Methods to instantiate and initialize domain objects
@@ -77,12 +77,12 @@ Supercedes methods in xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainOb
 ``Default`` +
 ``o.a.i.core`` +
 ``isis-core-metamodel``
-|Supercedes methods in xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`].
+|Supercedes methods in xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`].
 
 
 
 
-|xref:rgsvc.adoc#_rgsvc_api_Scratchpad[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_api_Scratchpad[`o.a.i.applib.` +
 `services.scratchpad` +
 `Scratchpad`]
 |Request-scoped service for interchanging information between and aggregating over multiple method calls; in particular for use by "bulk" actions (invoking of an action for all elements of a collection)
@@ -94,7 +94,7 @@ Supercedes methods in xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainOb
 
 
 
-|xref:rgsvc.adoc#_rgsvc_api_UserService[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_api_UserService[`o.a.i.applib.` +
 `services.xactn` +
 `UserService`]
 |Methods to access the currently-logged on user.
@@ -102,7 +102,7 @@ Supercedes methods in xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainOb
 ``Default`` +
 ``o.a.i.core`` +
 ``isis-core-metamodel``
-|Supercedes methods in xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`].
+|Supercedes methods in xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`].
 
 
 
@@ -135,7 +135,7 @@ There is also a number of deprecated domain services.
 |`Bulk.InteractionContext` +
 ``o.a.i.core`` +
 ``isis-core-applib``
-|Replaced by xref:rgsvc.adoc#_rgsvc_api_ActionInvocationContext[`ActionInvocationContext`]
+|Replaced by xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ActionInvocationContext[`ActionInvocationContext`]
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_integration-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_integration-api.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_integration-api.adoc
index 72c299a..302523f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_integration-api.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_integration-api.adoc
@@ -22,7 +22,7 @@ The table below summarizes the integration APIs defined by Apache Isis.  It also
 
 
 
-|xref:rgsvc.adoc#_rgsvc_api_BookmarkService[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[`o.a.i.applib.` +
 `services.bookmark` +
 `BookmarkService2`]
 |Convert object reference to a serializable "bookmark", and vice versa.
@@ -37,7 +37,7 @@ The table below summarizes the integration APIs defined by Apache Isis.  It also
 `Contributions`
 
 
-|xref:rgsvc.adoc#_rgsvc_api_DeepLinkService[`o.a.i.applib` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DeepLinkService[`o.a.i.applib` +
 `services.deeplink` +
 `DeepLinkService`]
 |Obtain a URL to a domain object (eg for use within an email or report)
@@ -47,7 +47,7 @@ The table below summarizes the integration APIs defined by Apache Isis.  It also
 |Implementation only usable within Wicket viewer
 
 
-|xref:rgsvc.adoc#_rgsvc_api_EmailService[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EmailService[`o.a.i.applib.` +
 `services.email` +
 `EmailService`]
 |Send a HTML email, optionally with attachments.
@@ -57,7 +57,7 @@ The table below summarizes the integration APIs defined by Apache Isis.  It also
 |
 
 
-|xref:rgsvc.adoc#_rgsvc_api_GuiceBeanProvider[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_api_GuiceBeanProvider[`o.a.i.applib.` +
 `services.guice` +
 `GuiceBeanProvider`]
 |Access to internal framework services initialized using Guice DI.
@@ -68,7 +68,7 @@ The table below summarizes the integration APIs defined by Apache Isis.  It also
 
 
 
-|xref:rgsvc.adoc#_rgsvc_api_JaxbService[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_api_JaxbService[`o.a.i.applib.` +
 `services.jaxb` +
 `JaxbService`]
 |Marshal and unmarshal JAXB-annotated view models to/from XML.
@@ -78,17 +78,17 @@ The table below summarizes the integration APIs defined by Apache Isis.  It also
 |
 
 
-|xref:rgsvc.adoc#_rgsvc_api_MementoService[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_api_MementoService[`o.a.i.applib.` +
 `services.memento` +
 `MementoService`]
-|Capture a serializable memento of a set of primitives or xref:rgsvc.adoc#_rgsvc_api_BookmarkService[bookmarks].  Primarily used internally, eg in support of commands/auditing.
+|Capture a serializable memento of a set of primitives or xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[bookmarks].  Primarily used internally, eg in support of commands/auditing.
 |`MementoServiceDefault` +
 ``o.a.i.core`` +
 ``isis-core-runtime``
 |
 
 
-|xref:rgsvc.adoc#_rgsvc_api_XmlSnapshotService[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_api_XmlSnapshotService[`o.a.i.applib.` +
 `services.xmlsnapshot` +
 `XmlSnapshotService`]
 |Generate an XML representation of an object and optionally a graph of related objects.

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_intro.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_intro.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_intro.adoc
index c6b2a95..38fbc01 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_intro.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_intro.adoc
@@ -18,11 +18,11 @@ below shows these categories:
 image::{_imagesdir}reference-services/categories.png[width="600px",link="{_imagesdir}reference-services/categories.png"]
 
 
-A small number of domain services can be considered both API and SPI; a good example is the xref:rgsvc.adoc#_rgsvc_api_EmailService[`EmailService`] that is of direct use for domain objects wishing to send out emails,
+A small number of domain services can be considered both API and SPI; a good example is the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EmailService[`EmailService`] that is of direct use for domain objects wishing to send out emails,
 but is also used by the framework to support the xref:ugvw.adoc#_ugvw_features_user-registration[user registration]
-functionality supported by the xref:ugvw.adoc#[Wicket viewer].   The same is true of the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`]; this can be used by domain objects to broadcast arbitrary events,
+functionality supported by the xref:ugvw.adoc#[Wicket viewer].   The same is true of the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`]; this can be used by domain objects to broadcast arbitrary events,
 but is also used by the framework to automatically emit events for
-xref:rgant.adoc#_rgant-Action_domainEvent[`@Action#domainEvent()`] etc.
+xref:../rgant/rgant.adoc#_rgant-Action_domainEvent[`@Action#domainEvent()`] etc.
 
 For these hybrid services we have categorized the service as an "API" service.  This chapter therefore contains only
 the strictly SPI services.
@@ -43,7 +43,7 @@ allowing you to easily mock out these services in your unit tests.
 The framework also defines a number of "internal" services.  These are not part of the framework's formal API, in that
 they use classes that are outside of the applib.  These internal framework services should be thought of as part of the
 internal design of the framework, and are liable to change from release to release.  The internal framework services 
-are documented in the xref:rgfis.adoc#[Framework Internal Services] guide.
+are documented in the xref:../rgfis/rgfis.adoc#[Framework Internal Services] guide.
 
 
 
@@ -78,13 +78,13 @@ public class Customer {
 For objects that are already persisted, the service is automatically injected just after the object is rehydrated by
 JDO/DataNucleus.
 
-For transient objects (instantiated programmatically), the xref:rgsvc.adoc#_rgsvc_api_FactoryService[`FactoryService`]'s
-``instantiate()`` method (or the deprecated xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`]'s
+For transient objects (instantiated programmatically), the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_FactoryService[`FactoryService`]'s
+``instantiate()`` method (or the deprecated xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`]'s
 ``newTransientInstance()`` method) will automatically inject the services.
 
 Alternatively the object can be instantiated simply using `new`, then services injected using
-xref:rgsvc.adoc#_rgsvc_api_ServiceRegistry[`ServiceRegistry`]'s ``injectServicesInto(...)`` method (or the deprecated
-xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`]'s ``injectServicesInto(...)`` method).
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ServiceRegistry[`ServiceRegistry`]'s ``injectServicesInto(...)`` method (or the deprecated
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`]'s ``injectServicesInto(...)`` method).
 
 
 
@@ -95,20 +95,20 @@ xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`]'s ``in
 The framework provides default implementations for many of the domain services.  This is convenient, but sometimes you
 will want to replace the default implementation with your own service implementation.
 
-The trick is to use the xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`]
+The trick is to use the xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`]
 attribute, specifying a low number (typically `"1"`).
 
 [NOTE]
 ====
 For a small number of domain services, all implementations are used (following the chain-of-responsibility pattern),
 not just the first one.  The services in question are:
-xref:rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`],
-xref:rgsvc.adoc#_rgsvc_spi_GridSystemService[`GridSystemService`], and
-xref:rgsvc.adoc#_rgsvc_spi_RoutingService[`RoutingService`].
+xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`],
+xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_GridSystemService[`GridSystemService`], and
+xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_RoutingService[`RoutingService`].
 ====
 
 For example, suppose you wanted to provide your own implementation of
-xref:rgsvc.adoc#_rgsvc_api_LocaleProvider[`LocaleProvider`].  Here's how:
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_LocaleProvider[`LocaleProvider`].  Here's how:
 
 [source,java]
 ----
@@ -176,65 +176,65 @@ image::{_imagesdir}reference-services/commands-and-events.png[width="960px",link
 
 To explain:
 
-* the (request-scoped) xref:rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`] captures the user's intention to
+* the (request-scoped) xref:../rgsvc/rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`] captures the user's intention to
 invoke an action or edit a property; this is held by the `Command` object.
 
-* if a xref:rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] has been configured, then this will be used to
+* if a xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] has been configured, then this will be used to
 create the `Command` object implementation, generally so that it can then also be persisted. +
 +
 If the action or property is annotated to be invoked in the background (using
-xref:rgant.adoc#_rgant-Action_command[`@Action#command...()`] or
-xref:rgant.adoc#_rgant-Property_command[`@Property#command...()`]) then no further work is done. But,
+xref:../rgant/rgant.adoc#_rgant-Action_command[`@Action#command...()`] or
+xref:../rgant/rgant.adoc#_rgant-Property_command[`@Property#command...()`]) then no further work is done. But,
 if the action/property is to be executed in the foreground, then the interaction continues.
 
-* the (request-scoped) xref:rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] domain service acts as a
+* the (request-scoped) xref:../rgsvc/rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] domain service acts as a
 factory for the ``Interaction`` object, which keeps track of the call-graph of executions (``Interaction.Execution``)
 of either action invocations or property edits.  In the majority of cases there is likely to be just a single top-level
-node of this graph, but for applications that use the xref:rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`]
+node of this graph, but for applications that use the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`]
 extensively each successive call results in a new child execution.
 
-* before and after each action invocation/property edit, a xref:rgcms.adoc#_rgcms_classes_domainevent[domain event] is
+* before and after each action invocation/property edit, a xref:../rgcms/rgcms.adoc#_rgcms_classes_domainevent[domain event] is
 may be broadcast to all subscribers.  Whether this occurs depends on whether the action/property has been annotated
-(using xref:rgant.adoc#_rgant-Action_domainEvent[`@Action#domainEvent()`] or
-xref:rgant.adoc#_rgant-Property_domainEvent[`@Property#domainEvent()`]). +
+(using xref:../rgant/rgant.adoc#_rgant-Action_domainEvent[`@Action#domainEvent()`] or
+xref:../rgant/rgant.adoc#_rgant-Property_domainEvent[`@Property#domainEvent()`]). +
 +
 (Note that susbcribers will also receive events for vetoing the action/property; this is not shown on the diagram).
 
 * As each execution progresses, and objects that are modified are "enlisted" into the (internal)
-xref:rgfis.adoc#_rgfis_spi_ChangedObjectsServiceInternal[`ChangedObjectsServiceInternal`] domain service.  Metrics as
+xref:../rgfis/rgfis.adoc#_rgfis_spi_ChangedObjectsServiceInternal[`ChangedObjectsServiceInternal`] domain service.  Metrics as
 to which objects are merely loaded into memory are also captured using the
-xref:rgsvc.adoc#_rgsvc_api_MetricsService[`MetricsService`] (not shown on the diagram).
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_MetricsService[`MetricsService`] (not shown on the diagram).
 
 * At the end of each execution, details of that execution are published through the (internal)
-xref:rgfis.adoc#_rgfis_spi_PublisherServiceInternal[`PublisherServiceInternal`] domain service.  This is only done for
-actions/properties annotated appropriate (with xref:rgant.adoc#_rgant-Action_publishing[`@Action#publishing()`] or
-xref:rgant.adoc#_rgant-Property_publishing[`@Property#publishing()`]).  +
+xref:../rgfis/rgfis.adoc#_rgfis_spi_PublisherServiceInternal[`PublisherServiceInternal`] domain service.  This is only done for
+actions/properties annotated appropriate (with xref:../rgant/rgant.adoc#_rgant-Action_publishing[`@Action#publishing()`] or
+xref:../rgant/rgant.adoc#_rgant-Property_publishing[`@Property#publishing()`]).  +
 +
 The internal service delegates in turn to any registered
-xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`] (deprecated) and also to any
-registered xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`]s (there may be more than one).
+xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`] (deprecated) and also to any
+registered xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`]s (there may be more than one).
 
 * At the end of each transaction, details of all changed objects are published, again through the (internal)
-xref:rgfis.adoc#_rgfis_spi_PublisherServiceInternal[`PublisherServiceInternal`] to any registered `PublishingService`
+xref:../rgfis/rgfis.adoc#_rgfis_spi_PublisherServiceInternal[`PublisherServiceInternal`] to any registered `PublishingService`
 or `PublisherService` implementations.  Only domain objects specified to be published with
-xref:rgant.adoc#_rgant-DomainObject_publishing[`@DomainObject#publishing()`] are published. +
+xref:../rgant/rgant.adoc#_rgant-DomainObject_publishing[`@DomainObject#publishing()`] are published. +
 +
 [NOTE]
 ====
 Note that it's possible for there to be more than one transaction per top-level interaction, by virtue of the
-xref:rgsvc.adoc#_rgsvc_api_TransactionService[`TransactionService`].
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_TransactionService[`TransactionService`].
 ====
 
 * Also at the end of each transaction, details of all changed properties are passed to any registered
-xref:rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditerService`] or
-xref:rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`] (the latter deprecated) by way of the (internal)
-xref:rgfis.adoc#_rgfis_spi_AuditingServiceInternal[`AuditingServiceInternal`] domain service.
+xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditerService`] or
+xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`] (the latter deprecated) by way of the (internal)
+xref:../rgfis/rgfis.adoc#_rgfis_spi_AuditingServiceInternal[`AuditingServiceInternal`] domain service.
 
-Implementations of xref:rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] can use the `Command#getMemento()`
-method to obtain a XML equivalent of that `Command`, reified using the xref:rgcms.adoc#_rgcms_schema-cmd[`cmd.xsd`]
+Implementations of xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] can use the `Command#getMemento()`
+method to obtain a XML equivalent of that `Command`, reified using the xref:../rgcms/rgcms.adoc#_rgcms_schema-cmd[`cmd.xsd`]
 schema. This can be converted back into a `CommandDto` using the `CommandDtoUtils` utility class (part of the applib).
 
-Similarly, implementations of xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] can use the
+Similarly, implementations of xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] can use the
 `InteractionDtoUtils` utility class to obtain a `InteractionDto` representing the interaction, either just for a single
 execution or for the entire call-graph.  This can be converted into XML in a similar fashion.
 
@@ -242,7 +242,7 @@ Likewise, the `PublishedObjects` class passed to the `PublisherService` at the e
 `PublishedObjects#getDto()` method which returns a `ChangesDto` instance.  This can be converted into XML using the
 `ChangesDtoUtils` utility class.
 
-One final point: multiple xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] implementations are supported
+One final point: multiple xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] implementations are supported
 because different implementations may have different responsibilities.  For example, the (non-ASF)
 http://github.com/isisaddons/isis-module-publishmq[Isis addons' publishmq] module is responsible for publishing
 messages onto an ActiveMQ event bus, for inter-system communication.  However, the SPI can also be used for profiling;

[47/58] [abbrv] isis git commit: ISIS-1521: further minor updates to ugfun.adoc

[da...@apache.org]

ISIS-1521: further minor updates to ugfun.adoc


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/480d6ff2
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/480d6ff2
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/480d6ff2

Branch: refs/heads/wip
Commit: 480d6ff24c2a66fc5a31fcb629677016bde0737e
Parents: 45db638
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Fri Apr 14 17:59:07 2017 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Thu Apr 20 09:09:30 2017 +0100

----------------------------------------------------------------------
 .../guides/rgcfg/_rgcfg_configuring-core.adoc   |   4 +-
 .../guides/ugbtb/_ugbtb_hints-and-tips.adoc     |   3 +
 .../_ugbtb_hints-and-tips_are-you-sure.adoc     |  76 ++++
 ...d-tips_simulating-collections-of-values.adoc |  23 ++
 ...-and-tips_subclass-properties-in-tables.adoc |  49 +++
 .../guides/ugbtb/_ugbtb_view-models.adoc        |   1 -
 .../guides/ugbtb/_ugbtb_view-models_jaxb.adoc   |   6 +-
 .../_ugbtb_view-models_programming-model.adoc   |   4 +-
 .../ugbtb/_ugbtb_view-models_use-cases.adoc     | 160 --------
 .../guides/ugfun/_ugfun_business-rules.adoc     |  89 ++++
 .../guides/ugfun/_ugfun_class-structure.adoc    |  42 ++
 .../ugfun/_ugfun_class-structure_actions.adoc   | 264 ++++++++++++
 .../_ugfun_class-structure_collections.adoc     | 121 ++++++
 .../_ugfun_class-structure_domain-services.adoc | 155 +++++++
 .../_ugfun_class-structure_inject-services.adoc | 103 +++++
 ...lass-structure_properties-vs-parameters.adoc |  38 ++
 .../_ugfun_class-structure_properties.adoc      | 411 +++++++++++++++++++
 .../main/asciidoc/guides/ugfun/_ugfun_crud.adoc |  29 ++
 .../ugfun/_ugfun_domain-class-ontology.adoc     |  43 ++
 ...n_domain-class-ontology_domain-entities.adoc |  86 ++++
 ...n_domain-class-ontology_domain-services.adoc | 214 ++++++++++
 ...ugfun_domain-class-ontology_view-models.adoc | 196 +++++++++
 .../ugfun/_ugfun_drop-downs-and-defaults.adoc   |  65 +++
 .../asciidoc/guides/ugfun/_ugfun_how-tos.adoc   |  20 -
 .../ugfun/_ugfun_how-tos_bulk-actions.adoc      |   8 -
 .../ugfun/_ugfun_how-tos_business-rules.adoc    |  72 ----
 .../ugfun/_ugfun_how-tos_class-structure.adoc   |  41 --
 .../_ugfun_how-tos_class-structure_actions.adoc | 264 ------------
 ...ow-tos_class-structure_class-definition.adoc | 201 ---------
 ...fun_how-tos_class-structure_collections.adoc |  99 -----
 ...how-tos_class-structure_inject-services.adoc | 103 -----
 ...lass-structure_properties-vs-parameters.adoc |  38 --
 ...gfun_how-tos_class-structure_properties.adoc | 397 ------------------
 .../guides/ugfun/_ugfun_how-tos_crud.adoc       |  29 --
 .../ugfun/_ugfun_how-tos_derived-members.adoc   |  48 ---
 .../ugfun/_ugfun_how-tos_domain-services.adoc   | 312 --------------
 .../_ugfun_how-tos_drop-downs-and-defaults.adoc |  65 ---
 ...how-tos_render-all-properties-in-tables.adoc |  49 ---
 ...ow-tos_simulating-collections-of-values.adoc |  23 --
 .../guides/ugfun/_ugfun_how-tos_ui-hints.adoc   |  15 -
 ...n_how-tos_ui-hints_action-icons-and-css.adoc |  58 ---
 ..._ugfun_how-tos_ui-hints_eager-rendering.adoc |  58 ---
 .../ugfun/_ugfun_how-tos_ui-hints_layout.adoc   |   9 -
 ...how-tos_ui-hints_names-and-descriptions.adoc |  47 ---
 ...ow-tos_ui-hints_object-titles-and-icons.adoc |  97 -----
 .../ugfun/_ugfun_how-tos_ui_are-you-sure.adoc   |  76 ----
 .../asciidoc/guides/ugfun/_ugfun_ui-hints.adoc  |  15 +
 .../_ugfun_ui-hints_action-icons-and-css.adoc   |  58 +++
 .../ugfun/_ugfun_ui-hints_eager-rendering.adoc  |  58 +++
 .../guides/ugfun/_ugfun_ui-hints_layout.adoc    |  14 +
 .../_ugfun_ui-hints_names-and-descriptions.adoc |  47 +++
 ..._ugfun_ui-hints_object-titles-and-icons.adoc |  97 +++++
 .../src/main/asciidoc/guides/ugfun/ugfun.adoc   |  12 +-
 .../src/main/asciidoc/guides/ugvw/ugvw.adoc     |   2 +-
 .../asciidoc/pages/screencasts/screencasts.adoc |   2 +-
 .../tg/_tg_stop-scaffolding-start-coding.adoc   |  20 +-
 56 files changed, 2325 insertions(+), 2311 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/rgcfg/_rgcfg_configuring-core.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcfg/_rgcfg_configuring-core.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcfg/_rgcfg_configuring-core.adoc
index c4948a0..4535000 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcfg/_rgcfg_configuring-core.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcfg/_rgcfg_configuring-core.adoc
@@ -597,14 +597,14 @@ Only intended for "emergency use" as a workaround while pending fix/patch to Apa
 |regex:css1, regex2:css2,...
 |Comma separated list of key:value pairs, where the key is a regex matching action names (eg `delete.*`) and the value is a link:http://getbootstrap.com/css/[Bootstrap] CSS button class (eg `btn-warning) to be applied (as per `@CssClass()`) to all action members matching the regex. +
 
-See xref:../ugfun/ugfun.adoc#_ugfun_how-tos_ui-hints_action-icons-and-css[UI hints] for more details.
+See xref:../ugfun/ugfun.adoc#_ugfun_ui-hints_action-icons-and-css[UI hints] for more details.
 
 |`isis.reflector.facet.` +
 `cssClassFa.patterns`
 |regex:fa-icon,regex2:fa-icon2,...
 |Comma separated list of key:value pairs, where the key is a regex matching action names (eg `create.*`) and the value is a link:http://fortawesome.github.io/Font-Awesome/icons/[font-awesome] icon name (eg `fa-plus`) to be applied (as per `@CssClassFa()`) to all action members matching the regex. +
 
-See xref:../ugfun/ugfun.adoc#_ugfun_how-tos_ui-hints_action-icons-and-css[UI hints] for more details.
+See xref:../ugfun/ugfun.adoc#_ugfun_ui-hints_action-icons-and-css[UI hints] for more details.
 
 
 |`isis.reflector.facet.` +

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips.adoc
index 51c76f0..8ebe0a7 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips.adoc
@@ -23,5 +23,8 @@ See also hints-n-tips chapters in the:
 * the xref:../ugbtb/ugbtb.adoc#_ugbtb_hints-and-tips[Beyond the Basics] guide (this chapter).
 
 
+include::_ugbtb_hints-and-tips_are-you-sure.adoc[leveloffset=+1]
 include::_ugbtb_hints-and-tips_how-to-handle-void-and-null-results.adoc[leveloffset=+1]
+include::_ugbtb_hints-and-tips_subclass-properties-in-tables.adoc[leveloffset=+1]
+include::_ugbtb_hints-and-tips_simulating-collections-of-values.adoc[leveloffset=+1]
 include::_ugbtb_hints-and-tips_how-to-implement-a-spellchecker.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_are-you-sure.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_are-you-sure.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_are-you-sure.adoc
new file mode 100644
index 0000000..66bc6d7
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_are-you-sure.adoc
@@ -0,0 +1,76 @@
+[[_ugbtb_hints-and-tips_are-you-sure]]
+= 'Are you sure?' idiom
+: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/
+
+
+Sometimes an action might perform irreversible changes.  In such a case it's probably a good idea for the UI to require that the
+end-user explicitly confirms that they intended to invoke the action.
+
+== Using action semantics
+
+One way to meet this requirement is using the framework's built-in xref:../rgant/rgant.adoc#_rgant-Action_semantics[`@Action#semantics()`] attribute:
+
+[source,java]
+----
+@Action(
+        semantics = SemanticsOf.IDEMPOTENT_ARE_YOU_SURE
+)
+public SimpleObject updateName(
+        @Parameter(maxLength = NAME_LENGTH)
+        @ParameterLayout(named = "New name")
+        final String name) {
+    setName(name);
+    return this;
+}
+----
+
+
+This will render as:
+
+image::{_imagesdir}/how-tos/tips-n-tricks/action-semantics-are-you-sure.png[]
+
+
+== Using a checkbox
+
+An alternative approach (for all versions of the framework) is to require the end-user to check a dummy checkbox parameter (and prevent the action from being invoked if the user hasn't checked that parameter).
+
+For example:
+
+image::{_imagesdir}/how-tos/tips-n-tricks/are-you-sure.png[]
+
+[NOTE]
+====
+Note that these screenshots shows an earlier version of the xref:../ugvw/ugvw.adoc#[Wicket viewer] UI (specifically, pre 1.8.0).
+====
+
+If the user checks the box:
+
+image::{_imagesdir}/how-tos/tips-n-tricks/are-you-sure-happy-case.png[]
+
+then the action will complete.
+
+However, if the user fails to check the box, then a validation message is shown:
+
+image::{_imagesdir}/how-tos/tips-n-tricks/are-you-sure-sad-case.png[]
+
+
+
+The code for this is pretty simple:
+
+[source,java]
+----
+public List<ToDoItem> delete(@Named("Are you sure?") boolean areYouSure) {
+    container.removeIfNotAlready(this);
+    container.informUser("Deleted " + container.titleOf(this));
+    return toDoItems.notYetComplete();          // <1>
+}
+public String validateDelete(boolean areYouSure) {
+    return areYouSure? null: "Please confirm you are sure";
+}
+----
+<1> invalid to return `this` (cannot render a deleted object)
+
+Note that the action itself does not use the boolean parameter, it is only
+used by the supporting xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_validate[`validate...()`] method.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_simulating-collections-of-values.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_simulating-collections-of-values.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_simulating-collections-of-values.adoc
new file mode 100644
index 0000000..f606ba7
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_simulating-collections-of-values.adoc
@@ -0,0 +1,23 @@
+[[_ugbtb_hints-and-tips_simulating-collections-of-values]]
+= Collections of values
+: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/
+
+
+
+Although in Apache Isis you can have properties of either values (string, number, date etc) or of (references to other) entities, with collections the framework (currently) only supports collections of (references to) entities.  That is, collections of values (a bag of numbers, say) are not supported.
+
+However, it is possible to simulate a bag of numbers using view models.
+
+
+== View Model
+
+NOTE: FIXME
+
+
+
+== Persistence Concerns
+
+NOTE: FIXME -  easiest to simply store using DataNucleus' support for collections, marked as xref:../rgant/rgant.adoc#_rgant-Programmatic[`@Programmatic`] so that it is ignored by Apache Isis.  Alternatively can store as json/xml in a varchar(4000) or clob and manually unpack.
+

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_subclass-properties-in-tables.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_subclass-properties-in-tables.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_subclass-properties-in-tables.adoc
new file mode 100644
index 0000000..7c29f55
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_subclass-properties-in-tables.adoc
@@ -0,0 +1,49 @@
+[[_ugbtb_hints-and-tips_subclass-properties-in-tables]]
+= Subclass properties in tables
+: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/
+
+
+
+Suppose you have a hierarchy of classes where a property is derived and abstract in the superclass, concrete implementations in the subclasses. For example:
+
+[source,java]
+----
+public abstract class LeaseTerm {
+    public abstract BigDecimal getEffectiveValue();
+    ...
+}
+
+public class LeaseTermForIndexableTerm extends LeaseTerm {
+    public BigDecimal getEffectveValue() { ... }
+    ...
+}
+----
+
+Currently the Wicket viewer will not render the property in tables (though the property is correctly rendered in views).
+
+[NOTE]
+====
+For more background on this workaround, see https://issues.apache.org/jira/browse/ISIS-582[ISIS-582].
+====
+
+The work-around is simple enough; make the method concrete in the superclass and return a dummy implementation, eg:
+
+[source,java]
+----
+public abstract class LeaseTerm {
+    public BigDecimal getEffectiveValue() {
+        return null;        // workaround for ISIS-582
+    }
+    ...
+}
+----
+
+
+Alternatively the implementation could throw a `RuntimeException`, eg
+
+[source,java]
+----
+throw new RuntimeException("never called; workaround for ISIS-582");
+----
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models.adoc
index dcd248a..0efd664 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models.adoc
@@ -12,7 +12,6 @@ This opens up a number of more advanced use cases.
 In this topic we'll explore those use cases, and learn the programming model and conventions to use view models in your application.
 
 
-include::_ugbtb_view-models_use-cases.adoc[leveloffset=+1]
 include::_ugbtb_view-models_programming-model.adoc[leveloffset=+1]
 include::_ugbtb_view-models_jaxb.adoc[leveloffset=+1]
 

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_jaxb.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_jaxb.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_jaxb.adoc
index 258f9e2..fe49916 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_jaxb.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_jaxb.adoc
@@ -1,12 +1,12 @@
 [[_ugbtb_view-models_jaxb]]
-= JAXB-annotated DTOs
+= JAXB-annotated View Models/DTOs
 :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/
 
 
 
-As noted in the xref:../ugbtb/ugbtb.adoc#_ugbtb_view-models_use-cases[introduction], view models can also be defined using JAXB annotations.
+As noted in the xref:../ugfun/ugfun.adoc#_ugfun_domain-class-ontology_view-models[introduction], view models can also be defined using JAXB annotations.
 The serialized form of these view models is therefore XML, which also enables these view models
 to act as DTOs.
 
@@ -18,7 +18,7 @@ In fact, these JAXB-annotated view models are in many regards the most powerful
 In contrast, using xref:../rgant/rgant.adoc#_rgant-ViewModel[`@ViewModel`] (or its xref:../rgant/rgant.adoc#_rgant-DomainObject_nature[`@DomainObject#nature()`] equivalent) will only manage the state of properties, but not collections.
 And if using the xref:../rgcms/rgcms.adoc#_rgcms_classes_super_ViewModel[`ViewModel`] interface, then the programmer must write all the state management (lots of boilerplate).
 
-* JAXB-annotated view models are editable.
+* JAXB-annotated view models are "in effect" editable.
 
 The examples in this section uses the DTO for `ToDoItem`, taken from the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp].
 This DTO is defined as follows:

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_programming-model.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_programming-model.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_programming-model.adoc
index d4bb007..2fd3a82 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_programming-model.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_programming-model.adoc
@@ -6,7 +6,9 @@
 
 
 
-So much for the theory; how should view models be implemented?  Fundamentally all view models' state is serialized into
+This section describes how to implement view models.
+
+Fundamentally all view models' state is serialized into
 a string memento; this memento is then held by the client (browser) in the form of a URL.  As you might imagine, this
 URL can become quite long, but Apache Isis offers a mechanism (the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UrlEncodingService[`UrlEncodingService`]) if it exceeds the maximum length for a URL
 (2083 characters).  Also, of course, this string memento must only contain characters that it is valid for use within

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_use-cases.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_use-cases.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_use-cases.adoc
deleted file mode 100644
index a58f57c..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_use-cases.adoc
+++ /dev/null
@@ -1,160 +0,0 @@
-[[_ugbtb_view-models_use-cases]]
-= Use Cases
-: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/
-
-
-When developing an Apache Isis application you will most likely start off with the persistent domain entities:
-`Customer`, `Order`, `Product`, and so on.  For some applications this may well suffice.  However, if the application
-needs to integrate with other systems, or if the application needs to support reasonably complex business processes, then you may need to look beyond just domain entities.  This section explores these use cases.
-
-[[__ugbtb_view-models_use-cases_externally-managed-entities]]
-== Externally-managed entities
-
-Sometimes the entities that make up your application are persisted not in the local JDO/DataNucleus database
-but reside in some other system, for example accessible only through a SOAP web service.  Logically that data
-might still be considered a domain entity and we might want to associate behaviour with it, however it cannot be
-modelled as a domain entity if only because JDO/DataNucleus doesn't know about the entity nor how to retrieve or
-update it.
-
-There are a couple of ways around this: we could either replicate the data somehow from the external system into the
- Isis-managed database (in which case it is once again just another domain entity), or we could set up a stub/proxy for
- the externally managed entity.  This proxy would hold the reference to the externally-managed domain entity (eg an
- external id), as well as the "smarts" to know how to interact with that entity (by making SOAP web service calls etc).
-
-The stub/proxy is a type of view model: a view - if you like - onto the domain entity managed by the external system.
-
-[NOTE]
-====
-DataNucleus does in fact define its own link:http://www.datanucleus.org/documentation/extensions/store_manager.html[Store Manager] extension point, so an alternative architecture would be to implement this interface such that DataNucleus
-could make the calls to the external system; these externally-persisted domain entities would therefore be modelled as regular `@PersistenceCapable` entities after all.  For entities not persisted externally the implementation would delegate down to the default RDBMS-specific `StoreManager` provided by DataNucleus itself.
-
-An implementation that supported only reading from an external entity ought to be comparatively straight-forward, but
-implementing one that also supported updating external entities would need to carefully consider error conditions if the
-external system is unavailable; distributed transactions are most likely difficult/impossible to implement (and not
-desirable in any case).
-====
-
-
-[[__ugbtb_view-models_use-cases_in-memory-entities]]
-== In-memory entities
-
-As a variation on the above, sometimes there are domain objects that are, conceptually at least entities, but whose
-state is not actually persisted anywhere, merely held in-memory (eg in a hash).
-
-A simple example might be read-only configuration data that is read from a config file (eg log4j appender
-definitions) but thereafter is presented in the UI just like any other entity.
-
-
-[[__ugbtb_view-models_use-cases_application-layer-view-models]]
-== Application-layer view models
-
-Domain entities (whether locally persisted using JDO/DataNucleus or managed externally) are the bread-and-butter of Apache Isis applications: the focus after all, should be on the business domain concepts and ensuring that they are
-solid.  Generally those domain entities will make sense to the business domain experts: they form the _ubiquitous language_ of the domain.  These domain entities are part of the domain layer.
-
-That said, it may not always be practical to expect end-users of the application to interact solely with those domain
-entities.  For example, it may be useful to show a dashboard of the most significant data in the system to a user,
-often pulling in and aggregating information from multiple points of the app.  Obtaining this information by hand (by
- querying the respective services/repositories) would be tedious and slow; far better to have a dashboard do the job for
- the end user.
-
-A dashboard object is a model of the most relevant state to the end-user, in other words it is (quite literally) a view
- model.  It is not a persisted entity, instead it belongs to the application layer.
-
-A view model need not merely aggregate data; it could also provide actions of its own.  Most likely these actions will
-be queries and will always ultimately just delegate down to the appropriate domain-layer service/repository.  But in
-some cases such view model actions might also modify state of underlying domain entities.
-
-Another common use for view models is to help co-ordinate complex business processes; for example to perform a
-quarterly invoicing run, or to upload annual interest rates from an Excel spreadsheet.  In these cases the view model
-might have some state of its own, but in most cases that state does not need to be persisted per se.
-
-.Desire Lines
-****
-One way to think of application view models is as modelling the "desire line": the commonly-trod path
-that end-users must follow to get from point A to point B as quickly as possible.
-
-To explain: there are link:http://ask.metafilter.com/62599/Where-the-sidewalk-ends[documented]
-link:https://sivers.org/walkways[examples]
-link:http://www.softpanorama.org/People/Wall/larry_wall_articles_and_interviews.shtml[that] architects of university
-campus will only add in paths some while after the campus buildings are complete: let the pedestrians figure out the
-routes they want to take.  The name we like best for this idea is "desire lines", though it has also been called
-a "desire path", "paving the path" or "paving the sidewalk".
-
-What that means is you should add view models _after_ having built up the domain layer, rather than before.  These view
-models pave that commonly-trod path, automating the steps that the end-user would otherwise have to do by hand.
-
-It takes a little practice though, because even when building the domain layer "first", you should still bear in mind
-what the use cases are that those domain entities are trying to support.  You certainly _shouldn't_ try to build out a
-domain layer that could support every conceivable use case before starting to think about view models.
-
-Instead, you should iterate.  Identify the use case/story/end-user objective that you will deliver value to the
-business.  Then build out the minimum domain entities to support that use case (refining the xref:../ugfun/ugfun.adoc#__ugfun_core-concepts_philosophy_domain-driven-design_ubiquitous-language[ubiquitous language] as you
-go).  Then, identify if there any view models that could be introduced which would simplify the end-user interactions
-with the system (perhaps automating several related use cases together).
-****
-
-[[__ugbtb_view-models_use-cases_dtos]]
-== DTOs
-
-DTOs (data transfer objects) are simple classes that (according to link:https://en.wikipedia.org/wiki/Data_transfer_object[wikipedia]) "carry data between processes".
-
-If those two processes are parts of the same overall application (the same team builds and deploys both server and
-client) then there's generally no need to define a DTO; just access the entities using Apache Isis'
-xref:../ugvro/ugvro.adoc#[RestfulObjects viewer].
-
-On the other hand, if the client consuming the DTO is a different application -- by which we mean developed/deployed by
-a different (possible third-party) team -- then the DTOs act as a formal contract between the provider and the consumer.
-In such cases, exposing domain entities over xref:../ugvro/ugvro.adoc#[RestfulObjects] would be
-"A Bad Thing"(TM) because the consumer would in effect have access to implementation details that could then not be
-easily changed by the producer.
-
-To support this use case, a view model can be defined such that it can act as a DTO.  This is done by annotating the
-class using JAXB annotations; this allows the consumer to obtain the DTO in XML format along with a corresponding
-XSD schema describing the structure of that XML.  A discussion of how that might be done using an ESB such as
-link:http://camel.apache.org[Apache Camel(TM)] follows xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_use-cases_dtos_consumers[below].
-
-In case it's not obvious, these DTOs are still usable as "regular" view models; they will render in the xref:../ugvw/ugvw.adoc#[Wicket viewer] just like any other.  In fact (as the xref:../ugbtb/ugbtb.adoc#_ugbtb_view-models_programming-model[programming model] section below makes clear), these JAXB-annotated view models are in many regards the most powerful of all the alternative ways of writing view models.
-
-
-It's also worth noting that it is also possible to download the XML (or XSD) straight from the UI, useful during development.
-The view model simply needs to implement the xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins_Dto[`Dto`] marker interface; the
-framework has xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins_Dto[mixins] that contribute the download actions to the view model.
-
-
-[[__ugbtb_view-models_use-cases_dtos_consumers]]
-=== DTO Consumers
-
-The actual consumers of DTOs will generally obtain the XML of the view models either by requesting the XML directly,
-eg using the xref:../ugvro/ugvro.adoc#[RestfulObjects viewer], or may have the XML sent to them asynchronously using an ESB
-such as Apache Camel.
-
-In the former case, the consumer requests the DTO by calling the REST API with the appropriate HTTP `Accept` header.
-An appropriate implementation of xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`] can then be
-used to return the appropriate DTO (as XML).
-
-For the latter case, one design is simply for the application to instantiate the view model, then call the
-xref:../rgsvc/rgsvc.adoc#_rgsvc_api_JaxbService[`JaxbService`] to obtain its corresponding XML.  This can then be published onto
-the ESB, for example using an http://activemq.apache.org[Apache ActiveMQ (TM)] queue.
-
-However, rather than try to push all the data that might be needed by any of these external systems in a single XML event
- (which would require anticipating all the requirements, likely a hopeless task), a better design is to publish only
- the fact that something of note has changed - ie, that an action on a domain object has been invoked - and then let the consumers call back to obtain other information if required.  This can once again be done by calling the REST API with
- an appropriate HTTP `Accept` header.
-
-[TIP]
-====
-This is an example of the link:https://leanpub.com/camel-design-patterns[VETRO pattern] (validate, enrich, transform, route, operate).  In our case we focus on the validation (to determine the nature of the inbound message, ie which action was
-invoked), and the enrich (callback to obtain a DTO with additional information required by the consumer).
-====
-
-The (non-ASF) http://github.com/isisaddons/isis-module-publishmq[Isis addons' publishmq] module provides an out-of-the-box solution of this design.  It provides an implementation of the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`],
-but which simply publishes instances of xref:../rgcms/rgcms.adoc#_rgcms_schema-aim[`ActionInvocationMemento`] to an ActiveMQ
-queue.  Camel (or similar) can then be hooked up to consume these events from this queue, and use a processor to
-parse the action memento to determine what has changed on the source system.  Thereafter, a subsequent Camel processor
-can then call back to the source - via the xref:../ugvro/ugvro.adoc[Restful Objects viewer] - to enrich the message with
-additional details using a DTO.
-
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_business-rules.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_business-rules.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_business-rules.adoc
new file mode 100644
index 0000000..e799572
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_business-rules.adoc
@@ -0,0 +1,89 @@
+[[_ugfun_business-rules]]
+= Business Rules
+: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/
+
+NOTE: FIXME
+
+
+
+== Visibility ("see it")
+
+NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_hide[`hide...()`]
+
+### Hide a Property
+
+### Hide a Collection
+
+### Hide an Action
+
+### Hide a Contributed Property, Collection or Action
+
+### All Members Hidden
+
+
+
+
+== Usability ("use it")
+
+NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_disable[`disable...()`]
+
+### Disable a Property
+
+### Disable a Collection
+
+### Disable an Action
+
+### Disable a Contributed Property, Collection or Action
+
+### All Members Unmodifiable (Disabling the Edit Button)
+
+Sometimes an object is unmodifiable.
+
+In the Wicket viewer this means disabling the edit button.
+
+#### Declarative
+
+`@DomainObject(editing=...)`
+
+#### Imperative
+
+
+
+== Validity ("do it")
+
+NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_validate[`validate...()`], xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_validateAddTo[`validateAddTo...()`], xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_validateRemoveFrom[`validateRemoveFrom...()`] and xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_validate[`validate()`]
+
+
+### Validate (change to) a Property
+
+### Validate (adding or removing from) a Collection
+
+### Validate (arguments to invoke) an Action
+
+### Validating a Contributed Property, Collection or Action
+
+### Declarative validation
+
+NOTE: FIXME - using xref:../rgant/rgant.adoc#_rgant-Parameter_mustSatisfy[`@Parameter#mustSatisfy()`], xref:../rgant/rgant.adoc#_rgant-Property_mustSatisfy[`@Property#mustSatisfy()`]
+
+
+
+
+
+
+
+== On modification
+
+NOTE: FIXME - detail here...
+
+=== Trigger on property change
+
+NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_modify[`modify...()`], xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_clear[`clear...()`]
+
+
+
+=== Trigger on collection change
+
+NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_addTo[`addTo...()`], xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_removeFrom[`removeFrom...()`]

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure.adoc
new file mode 100644
index 0000000..4ea4350
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure.adoc
@@ -0,0 +1,42 @@
+[[_ugfun_class-structure]]
+= Class Structure
+: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 works by building a metamodel of the domain objects: entities, xref:../ugbtb/ugbtb.adoc#_ugbtb_view-models[view model]s and services.
+The class methods of both entities and view models represent both state -- (single-valued) properties and (multi-valued) collections -- and behaviour -- actions.  The class members of domain services is simpler: just behaviour, ie actions.
+
+In the automatically generated UI a property is rendered as a field.
+This can be either of a value type (a string, number, date, boolean etc) or can be a reference to another entity.
+A collection is generally rendered as a table.
+
+In order for Apache Isis to build its metamodel the domain objects must follow some conventions: what we call the _Apache Isis Programming Model_.
+This is just an extension of the pojo / JavaBean standard of yesteryear: properties and collections are getters/setters, while actions are simply any remaining `public` methods.
+
+Additional metamodel semantics are inferred both imperatively from _supporting methods_ and declaratively from annotations.
+
+In this section we discuss the mechanics of writing domain objects that comply with Apache Isis' programming model.
+
+[TIP]
+====
+In fact, the Apache Isis programming model is extensible; you can teach Apache Isis new programming conventions and you can remove existing ones; ultimately they amount to syntax.
+The only real fundamental that can't be changed is the notion that objects consist of properties, collections and actions.
+
+You can learn more about extending Apache Isis programming model xref:../ugbtb/ugbtb.adoc#_ugbtb_programming-model[here].
+====
+
+
+include::_ugfun_class-structure_properties.adoc[leveloffset=+1]
+include::_ugfun_class-structure_collections.adoc[leveloffset=+1]
+include::_ugfun_class-structure_actions.adoc[leveloffset=+1]
+include::_ugfun_class-structure_inject-services.adoc[leveloffset=+1]
+
+include::_ugfun_class-structure_properties-vs-parameters.adoc[leveloffset=+1]
+
+include::_ugfun_class-structure_domain-services.adoc[leveloffset=+1]
+
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_actions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_actions.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_actions.adoc
new file mode 100644
index 0000000..613cbb9
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_actions.adoc
@@ -0,0 +1,264 @@
+[[_ugfun_class-structure_actions]]
+= Actions
+: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/
+
+
+
+While xref:../ugfun/ugfun.adoc#_ugfun_class-structure_properties[properties] and xref:../ugfun/ugfun.adoc#_ugfun_class-structure_collections[collections] define the state held by a domain object (its "know what" responsibilities), actions define the object's behaviour (its "know how-to" responsibilities).
+
+An application whose domain objects have only/mostly "know-what" responsibilities is pretty dumb: it requires that the end-user know the business rules and doesn't modify the state of the domain objects such that they are invalid (for example, an "end date" being before a "start date").
+Such applications are often called CRUD applications (create/read/update/delete).
+
+In more complex domains, it's not realistic/feasible to expect the end-user to have to remember all the different business rules that govern the valid states for each domain object.
+So instead actions allow those business rules to be encoded programmatically.
+An Apache Isis application doesn't try to constrain the end-user as to way in which they interact with the user (it doesn't attempt to define a rigid business process) but it does aim to ensure that business rule invariants are maintained, that is that business objects aren't allowed to go into an invalid state.
+
+For simple domain applications, you may want to start prototyping only with properties, and only later introduce actions (representing the most common business operations).
+But an alternative approach, recommended for more complex applications, is actually to start the application with all properties non-editable.
+Then, as the end-user requires the ability to modify some state, there is a context in which to ask the question "why does this state need to change?" and "are their any side-effects?" (ie, other state that changes at the same time, or other behaviour that should occur).
+If the state change is simple, for example just being able to correct an invalid address, or adding a note or comment, then that can probably be modelled as a simple editable property.
+But if the state change is more complex, then most likely an action should be used instead.
+
+
+[[__ugfun_class-structure_actions_defining-actions]]
+== Defining actions
+
+Broadly speaking, actions are all the `public` methods that are not getters or setters which represent properties or collections.
+This is a slight simplification; there are a number of other method prefixes (such as `hide` or `validate`) that represent xref:../ugfun/ugfun.adoc#_ugfun_business-rules[business rules]); these also not treated as actions.
+And, any method that are annotated with `@Programmatic` will also be excluded.
+But by and large, all other methods such as `placeOrder(...)` or `approveInvoice(...)` will be treated as actions.
+
+For example:
+
+[source,java]
+----
+@Action(semantics=SemanticsOf.IDEMPOTENT)       // <1>
+public ShoppingBasket addToBasket(
+        Product product,
+        @ParameterLayout(named="Quantity")      // <2>
+        int quantity
+        ) {
+    ...
+    return this;
+}
+----
+<1> `@Action` annotation is optional but used to specify additional domain semantics (such as being idempotent).
+<2> The names of action parameters (as rendered in the UI) will by default be the parameter types, not the paramter names.
+For the `product` parameter this is reasonable, but not so for the `quantity` parameter (which would by default show up with a name of "int".
+The `@ParameterLayout` annotation provides a UI hint to the framework.
+
+[TIP]
+====
+The (non-ASF) Isis addons' http://github.com/isisaddons/isis-metamodel-paraname8[paraname8] metamodel extension allows the parameter name to be used in the UI, rather than the type.
+====
+
+
+[[__ugfun_class-structure_actions_reference-parameter-types]]
+== (Reference) Parameter types
+
+Parameter types can be value types or reference types.
+In the case of primitive types, the end-user can just enter the value directly through the parameter field.
+In the case of reference types however (such as `Product`), a drop-down must be provided from which the end-user to select.
+This is done using either a supporting xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_choices[`choices`] or xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete`] method.
+The "choices" is used when there is a limited set of options, while "autoComplete" is used when there are large set of options such that the end-user must provide some characters to use for a search.
+
+For example, the `addToBasket(...)` action shown above might well have a :
+
+[source,java]
+----
+@Action(semantics=SemanticsOf.IDEMPOTENT)
+public ShoppingBasket addToBasket(
+        Product product,
+        @ParameterLayout(named="Quantity")
+        int quantity
+        ) {
+    ...
+    return this;
+}
+public List<Product> autoComplete0AddToBasket(              // <1>
+    @MinLength(3)                                           // <2>
+    String searchTerm) {
+    return productRepository.find(searchTerm);              // <3>
+}
+@javax.inject.Inject
+ProductRepository productRepository;
+----
+<1> Supporting `autoComplete` method.
+The "0" in the name means that this corresponds to parameter 0 of the "addToBasket" action (ie `Product`).
+It is also required to return a Collection of that type.
+<2> The xref:../rgant/rgant.adoc#_rgant_MinLength[`@MinLength`] annotation defines how many characters the end-user must enter before performing a search.
+<3> The implementation delegates to an injected repository service.  This is typical.
+
+Note that it is also valid to define "choices" and "autoComplete" for value types (such as `quantity`, above); it just isn't as common to do so.
+
+[[__ugfun_class-structure_actions_reference-parameter-types_removing-boilerplate]]
+=== Removing boilerplate
+
+To save having to define an `autoCompleteNXxx(...)` method everywhere that a reference to a particular type (such as `Product`) appears as an action parameter, it is also possible to use the `@DomainObject` annotation on `Product` itself:
+
+[source,java]
+----
+@DomainObject(
+    autoCompleteRepository=ProductRepository.class          // <1>
+    autoCompleteAction="find"                               // <2>
+)
+public class Product ... {
+    ...
+}
+----
+<1> Whenever an action parameter requiring a `Product` is defined, provide an autoComplete drop-down automatically
+<2> Use the "find" method of `ProductRepository` (rather than the default name of "autoComplete")
+
+(As noted above), if the number of available instances of the reference type is a small number (in other words, all of which could comfortably be shown in a drop-down) then instead the `choicesNXxx()` supporting method can be used.
+This too can be avoided by annotating the referenced class.
+
+For example, suppose we have an action to specify the `PaymentMethodType`, where there are only 10 or so such (Visa, Mastercard, Amex, Paypal etc).
+We could define this as:
+
+[source,java]
+----
+public Order payUsing(PaymentMethodType type) {
+    ...
+}
+----
+
+where `PaymentMethodType` would be annotated using:
+
+[source,java]
+----
+@DomainObject(
+    bounded=true                            // <1>
+)
+public class PaymentMethodType ... {
+    ...
+}
+----
+<1> only a small (ie "bounded") number of instances available, meaning that the framework should render all in a drop-down.
+
+
+[[__ugfun_class-structure_actions_collection-parameter-types]]
+== Collection Parameter types
+
+Action parameters can also be collections of values (for example `List<String>`), or can be collections of references (such as `List<Customer>`).
+
+For example:
+
+[source,java]
+----
+@Action(semantics=SemanticsOf.IDEMPOTENT)
+public ShoppingBasket addToBasket(
+        List<Product> products,
+        @ParameterLayout(named="Quantity") int quantity
+        ) {
+    ...
+    return this;
+}
+public List<Product> autoComplete0AddToBasket(@MinLength(3) String searchTerm) {
+    return ...
+}
+----
+
+As the example suggests, any collection parameter type must provide a way to select items, either by way of a "choices" or "autoComplete" supporting method or alternatively defined globally using xref:../rgant/rgant.adoc#_rgant_DomainObject[`@DomainObject`] on the referenced type (described xref:../ugfun/ugfun.adoc#__ugfun_class-structure_actions_reference-parameter-types_removing-boilerplate[above]).
+
+
+[[__ugfun_class-structure_actions_optional-parameters]]
+== Optional Parameters
+
+Whereas the xref:../ugfun/ugfun.adoc#__ugfun_class-structure_properties_optional-properties[optionality of properties] is defined using xref:../rgant/rgant.adoc#_rgant_Column_allowsNull[`@javax.jdo.annotations.Column#allowsNull()`], that JDO annotation cannot be applied to parameter types.
+Instead, either the xref:../rgant/rgant.adoc#_rgant_Nullable[`@Nullable`] annotation or the xref:../rgant/rgant.adoc#_rgant_Parameter_optionality[`@Parameter#optionality()`]  annotation/attribute is used.
+
+For example:
+
+[source,java]
+----
+@javax.jdo.annotations.Column(allowsNull="true")                // <1>
+@lombok.Getter @lombok.Setter
+private LocalDate shipBy;
+
+public Order invoice(
+                PaymentMethodType paymentMethodType,
+                @Nullable                                       // <2>
+                @ParameterLayout(named="Ship no later than")
+                LocalDate shipBy) {
+    ...
+    setShipBy(shipBy)
+    return this;
+}
+----
+<1> Specifies the property is optional.
+<2> Specifies the corresponding parameter is optional.
+
+See also xref:../ugfun/ugfun.adoc#_ugfun_class-structure_properties-vs-parameters[properties vs parameters].
+
+[[__ugfun_class-structure_actions_string-parameters]]
+== ``String`` Parameters (Length)
+
+Whereas the xref:../ugfun/ugfun.adoc#__ugfun_class-structure_properties_datatypes_strings[length of string properties] is defined using xref:../rgant/rgant.adoc#_rgant_Column_length[`@javax.jdo.annotations.Column#length()`], that JDO annotation cannot be applied to parameter types.
+Instead, the xref:../rgant/rgant.adoc#_rgant_Parameter_maxLength[`@Parameter#maxLength()`] annotation/attribute is used.
+
+For example:
+
+[source,java]
+----
+@javax.jdo.annotations.Column(length=50)                // <1>
+@lombok.Getter @lombok.Setter
+private String firstName;
+
+@javax.jdo.annotations.Column(length=50)
+@lombok.Getter @lombok.Setter
+private String lastName;
+
+public Customer updateName(
+                @Parameter(maxLength=50)                // <2>
+                @ParameterLayout(named="First name")
+                String firstName,
+                @Parameter(maxLength=50)
+                @ParameterLayout(named="Last name")
+                String lastName) {
+    setFirstName(firstName);
+    setLastName(lastName);
+    return this;
+}
+----
+<1> Specifies the property length using the JDO xref:../rgant/rgant.adoc#_rgant_Column_length[`@Column#length()`] annotation
+<2> Specifies the parameter length using the (Apache Isis) xref:../rgant/rgant.adoc#_rgant_Parameter_maxLength[`@Parameter#maxLength()`] annotation
+
+[IMPORTANT]
+====
+Incidentally, note in the above example that the new value is assigned to the properties using the setter methods; the action does not simply set the instance field directly.
+This is important, because it allows JDO/DataNucleus to keep track that this instance variable is "dirty" and so needs flushing to the database table before the transaction completes.
+====
+
+See also xref:../ugfun/ugfun.adoc#_ugfun_class-structure_properties-vs-parameters[properties vs parameters].
+
+[[__ugfun_class-structure_actions_bigdecimal-parameters]]
+== ``BigDecimal``s (Precision)
+
+Whereas the xref:../ugfun/ugfun.adoc#__ugfun_class-structure_properties_datatypes_bigdecimals[precision of BigDecimal properties] is defined using xref:../rgant/rgant.adoc#_rgant_Column_scale[`@javax.jdo.annotations.Column#scale()`], that JDO annotation cannot be applied to parameter types.
+Instead, the xref:../rgant/rgant.adoc#_rgant_Digits_fraction[`@javax.validation.constraints.Digits#fraction()`] annotation/attribute is used.
+
+For example:
+
+[source,java]
+----
+@javax.jdo.annotations.Column(scale=2)                              // <1>
+@lombok.Getter @lombok.Setter
+private BigDecimal discountRate;
+
+public Order updateDiscount(
+                @javax.validation.constraints.Digits(fraction=2)    // <2>
+                @ParameterLayout(named="Discount rate")
+                String discountRate) {
+    setDiscountRate(discountRate);
+    return this;
+}
+----
+<1> Specifies the property precision using xref:../rgant/rgant.adoc#_rgant_Column_scale[`@Column#scale()`]
+<2> Specifies the corresponding parameter precision using xref:../rgant/rgant.adoc#_rgant_Digits_fraction[`@Digits#fraction()`].
+
+See also xref:../ugfun/ugfun.adoc#_ugfun_class-structure_properties-vs-parameters[properties vs parameters].
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_collections.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_collections.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_collections.adoc
new file mode 100644
index 0000000..a3e09da
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_collections.adoc
@@ -0,0 +1,121 @@
+[[_ugfun_class-structure_collections]]
+= Collections
+: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/
+
+
+A collection is an instance variable of a domain object, of a collection type that holds references to other domain objects.
+For example, a `Customer` may have a collection of ``Order``s).
+
+It's ok for a xref:../ugfun/ugfun.adoc#__ugfun_class-structure_class-definition_entities[domain entity] to reference another domain entity, and for a xref:../ugfun/ugfun.adoc#__ugfun_class-structure_class-definition_view-models[view model] to reference both view model and domain entities.
+However, it isn't valid for a domain entity to hold a persisted reference to view model (DataNucleus will not know how to persist that view model).
+
+Formally speaking, a collection is simply a regular JavaBean getter, returning a collection type (subtype of `java.util.Collection`).
+Most collections (those that are modifiable) will also have a setter and (if persisted) a backing instance field.
+And collections properties will also have a number of annotations:
+
+* Apache Isis defines its own set own `@Collection` annotation for capturing domain semantics.
+It also provides a `@CollectionLayout` for UI hints (though the information in this annotation may instead be provided by a supplementary xref:../ugvw/ugvw.adoc#_ugvw_layout[`.layout.xml`] file
+
+* the collections of domain entities are often annotated with various JDO/DataNucleus annotations, most notable `javax.jdo.annotations.Persistent`.
+This and other annotations can be used to specify if the association is bidirectional, and whether to define a link table or not to hold foreign key columns.
+
+* for the collections of view models, then JAXB annotations such as `@javax.xml.bind.annotation.XmlElementWrapper` and `@javax.xml.bind.annotation.XmlElement` will be present
+
+Apache Isis recognises some of these annotations for JDO/DataNucleus and JAXB and infers some domain semantics from them (for example, the maximum allowable length of a string property).
+
+Unlike xref:../ugfun/ugfun.adoc#_ugfun_class-structure_properties[properties], the framework (at least, the xref:../ugvw/ugvw.adoc[Wicket viewer]) does not allow collections to be "edited".
+Instead, xref:../ugfun/ugfun.adoc#_ugfun_class-structure_actions[action]s can be written that will modify the contents of the collection as a side-effect.
+For example, a `placeOrder(...)` action will likely add an `Order` to the `Customer#orders` collection.
+
+Since writing getter and setter methods adds quite a bit of boilerplate, it's common to use link:https://projectlombok.org/[Project Lombok] to code generate these methods at compile time (using Java's annotation processor) simply by adding the `@lombok.Getter` and `@lombok.Setter` annotations to the field.
+
+
+
+[[__ugfun_class-structure_collections_mapping-bidir-1m]]
+== Mapping bidir 1:m
+
+Bidirectional one-to-many collections are one of the most common types of associations between two entities.
+In the parent object, the collection can be defined as:
+
+[source,java]
+----
+public class ParentObject
+        implements Comparable<ParentObject>{
+
+    @javax.jdo.annotations.Persistent(
+        mappedBy = "parent",                                                // <1>
+        dependentElement = "false"                                          // <2>
+    )
+    @Collection                                                             // <3>
+    @lombok.Getter @lombok.Setter
+    private SortedSet<ChildObject> children = new TreeSet<ChildObject>();   // <4>
+
+}
+----
+<1> indicates a bidirectional association; the foreign key pointing back to the `Parent` will be in the table for `ChildObject`
+<2> disable cascade delete
+<3> (not actually required in this case, because no attributes are set, but acts as a useful reminder that this collection will be rendered in the UI by Apache Isis)
+<4> uses a `SortedSet` (as opposed to some other collection type; discussion below)
+
+while in the child object you will have:
+
+[source,java]
+----
+public class ChildObject
+        implements Comparable<ChildObject> {    // <1>
+
+    @javax.jdo.annotations.Column(
+        allowsNull = "false"                    // <2>
+    )
+    @Property(editing = Editing.DISABLED)       // <3>
+    @lombok.Getter @lombok.Setter
+    private ParentObject parent;
+}
+----
+<1> implements `Comparable` because is mapped using a `SortedSet`
+<2> mandatory; every child must reference its parent
+<3> cannot be edited directly
+
+Generally speaking you should use `SortedSet` for collection types (as opposed to `Set`, `List` or `Collection`).
+JDO/Datanucleus does support the mapping of these other types, but RDBMS are set-oriented, so using this type introduces the least friction.
+
+[NOTE]
+====
+For further details on mapping associations, see the JDO/DataNucleus documentation for link:http://www.datanucleus.org/products/accessplatform_4_1/jdo/orm/one_to_many.html[one-to-many] associations, link:http://www.datanucleus.org/products/accessplatform_4_1/jdo/orm/many_to_one.html[many-to-one] associations, link:http://www.datanucleus.org/products/accessplatform_4_1/jdo/orm/many_to_many.html[many-to-many] associations, and so on.
+
+Also, while JDO/DataNucleus itself supports `java.util.Map` as a collection type, this is not supported by Apache Isis.
+If you do wish to use this collection type, then annotate the getter with `@Programmatic` so that it is ignored by the Apache Isis framework.
+====
+
+
+
+== Value vs Reference Types
+
+Apache Isis can (currently) only provide a UI for collections of references.
+While you can use DataNucleus to persist collections/arrays of value types, such properties must be annotated as `@Programmatic` so that they are ignored by Apache Isis.
+
+If you want to visualize an array of value types in Apache Isis, then one option is to wrap value in a view model, as explained xref:../ugfun/ugfun.adoc#_ugbtb_hints-and-tips_simulating-collections-of-values[elsewhere].
+
+
+
+[[__ugfun_class-structure_collections_derived-collections]]
+== Derived Collections
+
+A derived collection is simply a getter (no setter) that returns a `java.util.Collection` (or subtype).
+
+While derived properties and derived collections typically "walk the graph" to associated objects, there is nothing to prevent the returned value being the result of invoking a repository (domain service) action.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+    ...
+    public List<Order> getMostRecentOrders() {
+        return orderRepo.findMostRecentOrders(this, 5);
+    }
+}
+----
+

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_domain-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_domain-services.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_domain-services.adoc
new file mode 100644
index 0000000..ce7c3e7
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_domain-services.adoc
@@ -0,0 +1,155 @@
+[[_ugfun_class-structure_domain-services]]
+= Domain Services
+: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/
+
+
+This section looks at the programming conventions of writing your own domain services.
+
+
+== Typical Implementation
+
+Domain services are generally singletons that are automatically injected into other domain services.
+A very common usage is as a repository (to find/locate existing entities) or as a factory (to create new instances of entities).
+But services can also be exposed in the UI as top-level menus; and services are also used as a bridge to access technical resources (eg rendering a document object as a PDF).
+
+The Apache Isis framework itself also provides a large number of number of domain services, catalogued in the xref:../rgsvc/rgsvc.adoc#[Domain Services Reference Guide].
+Some of these are APIs (intended to be called by your application's own domain objects) and some are SPIs (implemented by your application and called by the framework, customising the way it works).
+
+The following is a typical menu service:
+
+[source,java]
+----
+@DomainService(                                                 // <1>
+        nature = NatureOfService.VIEW_MENU_ONLY
+)
+@DomainServiceLayout(                                           // <2>
+        named = "Simple Objects",
+        menuOrder = "10"
+)
+public class SimpleObjectMenu {
+
+    ...
+
+    @Action(semantics = SemanticsOf.SAFE)
+    @ActionLayout(bookmarking = BookmarkPolicy.AS_ROOT)
+    @MemberOrder(sequence = "2")
+    public List<SimpleObject> findByName(                       // <3>
+            @ParameterLayout(named="Name")
+            final String name
+    ) {
+        return simpleObjectRepository.findByName(name);
+    }
+
+    @javax.inject.Inject
+    SimpleObjectRepository simpleObjectRepository;              // <4>
+}
+----
+<1> The (Apache Isis) `@DomainService` annotation is used to identify the class as a domain service.
+Apache Isis scans the classpath looking for classes with this annotation, so there very little configuration other than to tell the framework which packages to scan underneath.
+The `VIEW_MENU_ONLY` nature indicates that this service's actions should be exposed as menu items.
+<2> The (Apache Isis) `@DomainServiceLayout` annotation provides UI hints.
+In the example above the menu is named "Simple Objects" (otherwise it would have defaulted to "Simple Object Menu", based on the class name, while the `menuOrder` attribute determines the order of the menu with respect to other menu services.
+<3> The `findByName` method is annotated with various Apache Isis annotations (`@Action`, `@ActionLayout` and `@MemberOrder`) and is itself rendered in the UI as a "Find By Name" menu item underneath the "Simple Objects" menu.
+The implementation delegates to an `SimpleObjectRepository` service, which is injected.
+<4> The `javax.inject.Inject` annotation instructs Apache Isis framework to inject the `SimpleObjectRepository` service into this domain object.
+The framework can inject into not just other domain services but will also automatically into domain entities and view models.
+There is further discussion of service injection xref:../ugfun/ugfun.adoc#_ugfun_class-structure_inject-services[below].
+
+
+
+
+== Scoped services
+
+By default all domain services are considered to be singletons, and thread-safe.
+
+Sometimes though a service's lifetime is applicable only to a single request; in other words it is request-scoped.
+
+The CDI annotation xref:../rgant/rgant.adoc#_rgant-RequestScoped[`@javax.enterprise.context.RequestScoped`] is used to indicate this fact:
+
+[source,java]
+----
+@javax.enterprise.context.RequestScoped
+public class MyService extends AbstractService {
+    ...
+}
+----
+
+The framework provides a number of request-scoped services, include a xref:../rgsvc/rgsvc.adoc#_rgsvc_api_Scratchpad[`Scratchpad`] service query results caching through the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_QueryResultsCache[`QueryResultsCache`], and support for co-ordinating bulk actions through the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ActionInvocationContext[`ActionInvocationContext`] service.  See the xref:../rgsvc/rgsvc.adoc[domain services] reference guide for further details.
+
+
+
+
+== Registering domain services
+
+The easiest way to register domain services is using xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`] to specify the modules
+which contain xref:../rgant/rgant.adoc#_rgant-DomainService[`@DomainService`]-annotated classes.
+
+For example:
+
+[source,ini]
+----
+public class MyAppManifest implements AppManifest {
+    public List<Class<?>> getModules() {
+        return Arrays.asList(
+                ToDoAppDomainModule.class,
+                ToDoAppFixtureModule.class,
+                ToDoAppAppModule.class,
+                org.isisaddons.module.audit.AuditModule.class);
+    }
+    ...
+}
+----
+
+will load all services in the packages underneath the four modules listed.
+
+An alternative (older) mechanism is to registered domain services in the `isis.properties` configuration file, under `isis.services` key (a comma-separated list); for example:
+
+[source,ini]
+----
+isis.services = com.mycompany.myapp.employee.Employees\,
+                com.mycompany.myapp.claim.Claims\,
+                ...
+----
+
+This will then result in the framework instantiating a single instance of each of the services listed.
+
+If all services reside under a common package, then the `isis.services.prefix` can specify this prefix:
+
+[source,ini]
+----
+isis.services.prefix = com.mycompany.myapp
+isis.services = employee.Employees,\
+                claim.Claims,\
+                ...
+----
+
+This is quite rare, however; you will often want to use default implementations of domain services that are provided by the framework and so will not reside under this prefix.
+
+Examples of framework-provided services (as defined in the applib) include clock, auditing, publishing, exception handling, view model support, snapshots/mementos, and user/application settings management; see the xref:../rgsvc/rgsvc.adoc[domain services] reference guide for further details.
+
+
+
+== Initialization
+
+Services can optionally declare lifecycle callbacks to initialize them (when the app is deployed) and to shut them down (when the app is undeployed).
+
+An Apache Isis session _is_ available when initialization occurs (so services can interact with the object store, for example).
+
+
+The framework will call any `public` method annotated with xref:../rgant/rgant.adoc#_rgant-PostConstruct[`@PostConstruct`] with either no arguments of an argument of type `Map<String,String>`
+
+or
+
+In the latter case, the framework passes in the configuration (`isis.properties` and any other component-specific configuration files).
+
+
+Shutdown is similar; the framework will call any method annotated with xref:../rgant/rgant.adoc#_rgant-PreDestroy[`@PreDestroy`].
+
+
+
+== The getId() method
+
+Optionally, a service may provide a xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_getId[`getId()`] method.  This method returns a logical identifier for a service, independent of its implementation.
+

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_inject-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_inject-services.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_inject-services.adoc
new file mode 100644
index 0000000..fb09fe1
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_inject-services.adoc
@@ -0,0 +1,103 @@
+[[_ugfun_class-structure_inject-services]]
+= Injecting services
+: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 autowires (automatically injects) domain services into each entity, as well as into the domain services themselves, using either method injection or field injection.
+The framework defines many additional services (such as xref:../rgsvc/rgsvc.adoc#_rgsvc_api_RepositoryService[`RepositoryService`]); these are injected in exactly the same manner.
+
+Sometimes there may be multiple services that implement a single type.
+This is common for example for SPI service, whereby one module defines an SPI service, and other module(s) in the application implement that service.
+To support this, the framework also allows lists of services to be injected.
+
+When there are multiple service implementations of a given type, the framework will inject the service with highest priority, as defined through xref:../rgant/rgant.adoc#_rgant_DomainService_menuOrder[`@DomainService#menuOrder()`] (even for domain services that are not menus), lowest first.
+If a list of services is injected, then that list will be ordered according to `menuOrder`, again lowest first.
+
+
+
+[NOTE]
+====
+Isis currently does _not_ support qualified injection of services; the domain service of each type must be distinct from any other.
+
+If you find a requirement to inject two instances of type `SomeService`, say, then the work-around is to create trivial subclasses `SomeServiceA` and `SomeServiceB` and inject these instead.
+====
+
+
+== Field Injection
+
+Field injection is recommended, using the `@javax.inject.Inject` annotation.
+For example:
+
+[source,java]
+----
+public class Customer {
+    ...
+    @javax.inject.Inject
+    OrderRepository orderRepository;
+}
+----
+
+To inject a list of services, use:
+
+[source,java]
+----
+public class DocumentService {
+    ...
+    @javax.inject.Inject
+    List<PaperclipFactory> paperclipFactories;
+}
+----
+
+We recommend using default rather than `private` visibility so that the field can be mocked out within unit tests (placed in the same package as the code under test).
+
+
+
+
+== Method Injection
+
+The framework also supports two forms of method injection.
+All that is required to inject a service into a entity/service is to provide an appropriate method or field.
+The name of the method does not matter, only that it is prefixed either `set` or `inject`, is public, and has a single parameter of the correct type.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+    private OrderRepository orderRepository;
+    public void setOrderRepository(OrderRepository orderRepository) {
+        this.orderRepository = orderRepository;
+    }
+    ...
+}
+----
+
+or alternatively, using 'inject' as the prefix:
+
+[source,java]
+----
+public class Customer {
+    private OrderRepository orderRepository;
+    public void injectOrderRepository(OrderRepository orderRepository) {
+        this.orderRepository = orderRepository;
+    }
+    ...
+}
+----
+
+Lists of services can be injected in a similar manner.
+
+Note that the method name can be anything; it doesn't need to be related to the type being injected.
+
+
+== Constructor injection
+
+Simply to note that constructor injection is _not_ supported by Apache Isis (and is unlikely to be, because the JDO specification for entities requires a no-arg constructor).
+
+
+
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_properties-vs-parameters.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_properties-vs-parameters.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_properties-vs-parameters.adoc
new file mode 100644
index 0000000..a0a926a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_properties-vs-parameters.adoc
@@ -0,0 +1,38 @@
+[[_ugfun_class-structure_properties-vs-parameters]]
+= Properties vs Parameters
+: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/
+
+
+In many cases the value types of properties and of action parameters align.
+For example, a `Customer` entity might have a `surname` property, and there might also be corresponding `changeSurname`.
+Ideally we want the surname property and surname action parameter to use the same value type.
+
+Since JDO/DataNucleus handles persistence, its annotations are requiredto specify semantics such as optionality or maximum length on properties.
+However, they cannot be applied to action parameters.
+It is therefore necessary to use Apache Isis' equivalent annotations for action parameters.
+
+The table below summarises the equivalence of some of the most common cases.
+
+.Comparing annotations of Properties vs Action Parameters
+[cols="2,3,3", options="header"]
+|===
+|value type/semantic
+|(JDO) property
+|action parameter
+
+|string (length)
+|`@javax.jdo.annotations.Column(length=50)`
+|`@javax.jdo.annotations.Parameter(maxLength=50)`
+
+|big decimal (precision)
+|`@javax.jdo.annotations.Column(scale=2)`
+|`@javax.validation.constraints.Digits(fraction=2)`
+
+|optionality
+|`@Column(allowsNull="true")`
+|`@Nullable` or `ParameterLayout(optionality=Optionality.OPTIONAL`) (also `@Optional`, now deprecated)
+|===
+
+

[41/58] [abbrv] isis git commit: ISIS-1521: adds hints-n-tips sections for most of the user guides, and distributes out tips from dg.adoc as appropriate

[da...@apache.org]

http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_hints-and-tips_i18n-label-in-wicket-viewer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_hints-and-tips_i18n-label-in-wicket-viewer.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_hints-and-tips_i18n-label-in-wicket-viewer.adoc
new file mode 100644
index 0000000..54b83d7
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_hints-and-tips_i18n-label-in-wicket-viewer.adoc
@@ -0,0 +1,26 @@
+[[_ugvw_hints-and-tips_i18n-label-in-wicket-viewer]]
+= How i18n the Wicket viewer?
+: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/
+
+
+
+From link:http://isis.markmail.org/thread/ctppmtcbsf4iskzi[this thread] on the Apache Isis users mailing list:
+
+* _I am trying to internationalize the label descriptions of form actions, eg those in `ActionParametersFormPanel`.
+Referencing those via their message id inside a .po file didn't work either.
+Can this be done?_
+
+
+The above FAQ was raised against `1.10.0`.  As of `1.11.0` (due to link:https://issues.apache.org/jira/browse/ISIS-1093[ISIS-1093]) it _is_ now possible to internationalize both the Wicket viewer's labels as well as the regular translations of the domain object metadata using the `.po` translation files as supported by the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_TranslationService[`TranslationService`].
+
+Full details of the ``msgId``s that must be added to the `translations.po` file can be found in xref:guides/ugbtb.adoc#__ugbtb_i18n_wicket-viewer[i18n] section of the xref:../ugbtb/ugbtb.adoc#[beyond the basics] guide.
+
+In prior releases (`1.10.0` and earlier) it was necessary to use link:https://ci.apache.org/projects/wicket/guide/6.x/guide/i18n.html#i18n_3[Wicket's internationalization support], namely resource bundles.  This is still supported (as a fallback):
+
+* create a directory structure inside the webapp resource folder following that pattern `org.apache.isis.viewer.wicket.ui.components.actions`
+
+* Inside there create an equivalent `ActionParametersFormPanel_xx_XX.properties` or `ActionParametersFormPanel_xx.properties` file for the various locales that you want to support (eg `ActionParametersFormPanel_en_UK.properties`, `ActionParametersFormPanel_en_US.properties`, `ActionParametersFormPanel_de.properties` and so on).
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_hints-and-tips_per-user-themes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_hints-and-tips_per-user-themes.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_hints-and-tips_per-user-themes.adoc
new file mode 100644
index 0000000..43c8835
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_hints-and-tips_per-user-themes.adoc
@@ -0,0 +1,91 @@
+[[_ugvw_hints-and-tips_per-user-themes]]
+= Per-user Themes
+: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/
+
+
+From link:http://isis.markmail.org/thread/kb4442niwwbnghey[this thread] on the Apache Isis users mailing list:
+
+* _Is it possible to have each of our resellers (using our Isis application) use there own theme/branding with their own logo and colors?
+Would this also be possible for the login page, possibly depending on the used host name?_
+
+
+Yes, you can do this, by installing a custom implementation of the Wicket Bootstrap's `ActiveThemeProvider`.
+
+The http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] (non-ASF) actually link:https://github.com/isisaddons/isis-app-todoapp/tree/61b8114a8e01dbb3c380b31cf09eaed456407570[does this], storing the info via the http://github.com/isisaddons/isis-module-settings[Isis addons' settings module] settings modules:
+
+
+[source,java]
+.IActiveThemeProvider implementation
+----
+public class UserSettingsThemeProvider implements ActiveThemeProvider {
+    ...
+    @Override
+    public ITheme getActiveTheme() {
+        if(IsisContext.getSpecificationLoader().isInitialized()) {
+            final String themeName = IsisContext.doInSession(new Callable<String>() {
+                @Override
+                public String call() throws Exception {
+                    final UserSettingsService userSettingsService =
+                        lookupService(UserSettingsService.class);
+                    final UserSetting activeTheme = userSettingsService.find(
+                            IsisContext.getAuthenticationSession().getUserName(),
+                            ACTIVE_THEME);
+                    return activeTheme != null ? activeTheme.valueAsString() : null;
+                }
+            });
+            return themeFor(themeName);
+        }
+        return new SessionThemeProvider().getActiveTheme();
+    }
+    @Override
+    public void setActiveTheme(final String themeName) {
+        IsisContext.doInSession(new Runnable() {
+            @Override
+            public void run() {
+                final String currentUsrName =
+                    IsisContext.getAuthenticationSession().getUserName();
+                final UserSettingsServiceRW userSettingsService =
+                        lookupService(UserSettingsServiceRW.class);
+                final UserSettingJdo activeTheme =
+                        (UserSettingJdo) userSettingsService.find(
+                                                currentUsrName, ACTIVE_THEME);
+                if(activeTheme != null) {
+                    activeTheme.updateAsString(themeName);
+                } else {
+                    userSettingsService.newString(
+                        currentUsrName, ACTIVE_THEME, "Active Bootstrap theme for user", themeName);
+                }
+            }
+        });
+    }
+    private ITheme themeFor(final String themeName) {
+        final ThemeProvider themeProvider = settings.getThemeProvider();
+        if(themeName != null) {
+            for (final ITheme theme : themeProvider.available()) {
+                if (themeName.equals(theme.name()))
+                    return theme;
+            }
+        }
+        return themeProvider.defaultTheme();
+    }
+    ...
+}
+----
+
+and
+
+[source,java]
+.Using the ActiveThemeProvider
+----
+@Override
+protected void init() {
+    super.init();
+
+    final IBootstrapSettings settings = Bootstrap.getSettings();
+    settings.setThemeProvider(new BootswatchThemeProvider(BootswatchTheme.Flatly));
+
+    settings.setActiveThemeProvider(new UserSettingsThemeProvider(settings));
+}
+----

http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/adocs/documentation/src/main/asciidoc/guides/ugvw/ugvw.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/ugvw.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/ugvw.adoc
index 4ddba0d..fde7dbc 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/ugvw.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/ugvw.adoc
@@ -53,8 +53,8 @@ include::_ugvw_features.adoc[leveloffset=+1]
 include::_ugvw_configuration-properties.adoc[leveloffset=+1]
 include::_ugvw_layout.adoc[leveloffset=+1]
 include::_ugvw_customisation.adoc[leveloffset=+1]
-
 include::_ugvw_extending.adoc[leveloffset=+1]
+include::_ugvw_hints-and-tips.adoc[leveloffset=+1]
 
 include::_ugvw_isis-addons.adoc[leveloffset=+1]
 

[16/58] [abbrv] isis git commit: ISIS-1521: moves faq from ugfun to dg.adoc, renames to 'hints-n-tips'

[da...@apache.org]

ISIS-1521: moves faq from ugfun to dg.adoc, renames to 'hints-n-tips'


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/0c22c0a3
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/0c22c0a3
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/0c22c0a3

Branch: refs/heads/wip
Commit: 0c22c0a392cce587e6448d438154d8c5063051c7
Parents: add8cef
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Fri Apr 14 15:12:14 2017 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Thu Apr 20 09:09:29 2017 +0100

----------------------------------------------------------------------
 .../asciidoc/guides/dg/_dg_hints-and-tips.adoc  | 23 +++++
 .../dg/_dg_hints-and-tips_enabling-logging.adoc | 41 +++++++++
 .../dg/_dg_hints-and-tips_enhance-only.adoc     | 25 ++++++
 ...nd-tips_how-run-fixtures-on-app-startup.adoc | 24 ++++++
 ...ips_how-to-handle-void-and-null-results.adoc | 79 +++++++++++++++++
 ...nd-tips_how-to-implement-a-spellchecker.adoc | 29 +++++++
 ...ts-and-tips_i18n-label-in-wicket-viewer.adoc | 26 ++++++
 .../dg/_dg_hints-and-tips_per-user-themes.adoc  | 91 ++++++++++++++++++++
 ...g_hints-and-tips_restful-image-property.adoc | 25 ++++++
 ...tips_subtype-entity-not-fully-populated.adoc | 60 +++++++++++++
 .../src/main/asciidoc/guides/dg/dg.adoc         |  3 +-
 .../main/asciidoc/guides/ugfun/_ugfun_faqs.adoc | 21 -----
 .../ugfun/_ugfun_faqs_enabling-logging.adoc     | 41 ---------
 .../guides/ugfun/_ugfun_faqs_enhance-only.adoc  | 25 ------
 ...un_faqs_how-run-fixtures-on-app-startup.adoc | 24 ------
 ...aqs_how-to-handle-void-and-null-results.adoc | 79 -----------------
 ...un_faqs_how-to-implement-a-spellchecker.adoc | 29 -------
 ..._ugfun_faqs_i18n-label-in-wicket-viewer.adoc | 26 ------
 .../ugfun/_ugfun_faqs_per-user-themes.adoc      | 91 --------------------
 .../_ugfun_faqs_restful-image-property.adoc     | 25 ------
 ...faqs_subtype-entity-not-fully-populated.adoc | 60 -------------
 .../src/main/asciidoc/guides/ugfun/ugfun.adoc   |  2 +-
 22 files changed, 426 insertions(+), 423 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc
new file mode 100644
index 0000000..67d89bd
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc
@@ -0,0 +1,23 @@
+[[_dg_hints-and-tips]]
+= Hints and Tips
+: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/
+:toc: right
+
+
+
+This chapter has FAQs (with solutions) for problems we've encountered ourselves or have been raised on the
+Apache Isis mailing lists.
+
+See also xref:ugvro.adoc#_ugvro_hints-and-tips[Restful Objects hints-n-tips].
+
+include::_dg_hints-and-tips_enabling-logging.adoc[leveloffset=+1]
+include::_dg_hints-and-tips_subtype-entity-not-fully-populated.adoc[leveloffset=+1]
+include::_dg_hints-and-tips_restful-image-property.adoc[leveloffset=+1]
+include::_dg_hints-and-tips_enhance-only.adoc[leveloffset=+1]
+include::_dg_hints-and-tips_per-user-themes.adoc[leveloffset=+1]
+include::_dg_hints-and-tips_i18n-label-in-wicket-viewer.adoc[leveloffset=+1]
+include::_dg_hints-and-tips_how-to-handle-void-and-null-results.adoc[leveloffset=+1]
+include::_dg_hints-and-tips_how-to-implement-a-spellchecker.adoc[leveloffset=+1]
+include::_dg_hints-and-tips_how-run-fixtures-on-app-startup.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_enabling-logging.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_enabling-logging.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_enabling-logging.adoc
new file mode 100644
index 0000000..af3ecc3
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_enabling-logging.adoc
@@ -0,0 +1,41 @@
+[[_dg_hints-and-tips_enabling-logging]]
+= 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/
+
+Sometimes you just need to see what is going on.
+There are various ways in which logging can be enabled, here are the ones we tend to use.
+
+* In Apache Isis +
++
+Modify `WEB-INF/logging.properties` (a log4j config file)
+
+* In DataNucleus +
++
+As per the http://www.datanucleus.org/products/accessplatform/logging.html[DN logging page]
+
+* In the JDBC Driver +
++
+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:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
+
+* In the database +
++
+Details below.
+
+
+Database logging can be configured:
+
+* for HSQLDB +
++
+by adding`;sqllog=3` to the end of the JDBC URL.
+
+* for PostgreSQL: +
++
+Can change `postgresql\9.2\data\postgresql.conf`; see link:http://www.postgresql.org/docs/9.2/static/runtime-config-logging.html[this article] for details.
+
+* for MS SQL Server Logging: +
++
+We like to use the excellent SQL Profiler tool.
+

http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_enhance-only.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_enhance-only.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_enhance-only.adoc
new file mode 100644
index 0000000..aa6bff9
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_enhance-only.adoc
@@ -0,0 +1,25 @@
+[[_dg_hints-and-tips_enhance-only]]
+= Enhance only (IntelliJ)
+: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/
+
+
+From the Apache Isis mailing list is:
+
+* _Is there a simple way to make a run configuration in IntelliJ for running the datanucleus enhancer before running integration test?_
+
+Yes, you can; here's one way:
+
+* Duplicate your run configuration for running the webapp
+** the one where the main class is `org.apache.isis.WebServer`
+** there's a button for this on the run configurations dialog.
+* then, on your copy change the main class to `org.apache.isis.Dummy`
+
+Or, you could just write a small shell script and run from the command line:
+
+[source,bash]
+.enhance.sh
+----
+mvn -pl dom datanucleus:enhance -o
+----

http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-run-fixtures-on-app-startup.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-run-fixtures-on-app-startup.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-run-fixtures-on-app-startup.adoc
new file mode 100644
index 0000000..89a1547
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-run-fixtures-on-app-startup.adoc
@@ -0,0 +1,24 @@
+[[_dg_hints-and-tips_how-run-fixtures-on-app-startup]]
+= How run fixtures on startup?
+: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/
+
+
+From this link:http://isis.markmail.org/thread/g6amfj2eyf2xfjbr[thread] on the Apache Isis users mailing list:
+
+* _my fixtures have grown into a couple of files the application needs to read in when it starts the first time (and possibly later on when the files content change).
+What is the right way to do this?
+Hook up into the webapp start?
+Use events?_
+
+
+The standard approach is to use xref:ugtst.adoc#_ugtst_fixture-scripts[fixture scripts].
+These can be run in on start-up typically by being specified in the xref:rgcsm.adoc#_rgcsm_classes_AppManifest-bootstrapping[`AppManifest`], see for
+example the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype].
+
+Alternatively just set "isis.fixtures" and "isis.persistor.datanucleus.install-fixtures" properties.
+
+In terms of implementations, you might also want to check out the (non-ASF) http://github.com/isisaddons/isis-module-excel[Isis addons' excel] module, by using link:https://github.com/isisaddons/isis-module-excel/blob/master/dom/src/main/java/org/isisaddons/module/excel/dom/ExcelFixture.java[`ExcelFixture`] and overriding `ExcelFixtureRowHandler` (same package).
+An example can be found in this (non ASF) link:https://github.com/incodehq/contactapp[contactapp], see link:https://github.com/incodehq/contactapp/blob/master/backend/fixture/src/main/java/domainapp/fixture/scenarios/demo/ContactRowHandler.java[`ContactRowHandler`].
+

http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-to-handle-void-and-null-results.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-to-handle-void-and-null-results.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-to-handle-void-and-null-results.adoc
new file mode 100644
index 0000000..76b3a2e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-to-handle-void-and-null-results.adoc
@@ -0,0 +1,79 @@
+[[_dg_hints-and-tips_how-to-handle-void-and-null-results]]
+= How to handle void/null results
+: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/
+
+
+
+From this link:http://isis.markmail.org/thread/yf7qdeiu3vrvk2ei[thread] on the Apache Isis users mailing list:
+
+* _When using a `void` action, let\u2019s say a remove action, the user is redirected to a
+page "no results".
+When clicking the back button in the browser the user sees "Object not found" (since you\u2019ve just deleted this object)._
+
+* _You can return a list for example to prevent the user from being redirect to a
+  "No results" page, but I think it\u2019s not the responsibility of the controllers in
+  the domain model._
+
+* _A solution could be that wicket viewer goes back one page when
+  encountering a deleted object.
+And refresh the current page when receiving a null response or invoking a void action.
+But how to implement this?_
+
+One way to implement this idea is to provide a custom implementation of the xref:rgsvc.adoc#_rgsvc_spi_RoutingService[`RoutingService`] SPI domain service.
+The default implementation will either return the current object (if not null), else the home page (as defined by xref:rgant.adoc#_rgant-HomePage[`@HomePage`]) if one exists.
+
+The following custom implementation refines this to use the breadcrumbs (available in the Wicket viewer) to return the first non-deleted domain object found in the list of breadcrumbs:
+
+[source,java]
+----
+@DomainService(nature = NatureOfService.DOMAIN)
+@DomainServiceLayout(menuOrder = "1")                                           // <1>
+public class RoutingServiceUsingBreadcrumbs extends RoutingServiceDefault {
+    @Override
+    public Object route(final Object original) {
+        if(original != null) {                                                  // <2>
+            return original;
+        }
+        container.flush();                                                      // <3>
+
+        final BreadcrumbModelProvider wicketSession =                           // <4>
+            (BreadcrumbModelProvider) AuthenticatedWebSession.get();
+        final BreadcrumbModel breadcrumbModel =
+            wicketSession.getBreadcrumbModel();
+        final List<EntityModel> breadcrumbs = breadcrumbModel.getList();
+
+        final Optional<Object> firstViewModelOrNonDeletedPojoIfAny =
+                breadcrumbs.stream()                                            // <5>
+                .filter(entityModel -> entityModel != null)
+                .map(EntityModel::getObject)                                    // <6>
+                .filter(objectAdapter -> objectAdapter != null)
+                .map(ObjectAdapter::getObject)                                  // <7>
+                .filter(pojo -> !(pojo instanceof Persistable) ||
+                                !((Persistable)pojo).dnIsDeleted())             // <8>
+                .findFirst();
+
+        return firstViewModelOrNonDeletedPojoIfAny.orElse(homePage());          // <9>
+    }
+    private Object homePage() {
+        return homePageProviderService.homePage();
+    }
+    @Inject
+    HomePageProviderService homePageProviderService;
+    @Inject
+    DomainObjectContainer container;
+}
+----
+<1> override the default imlpementation
+<2> if a non-null object was returned, then return this
+<3> ensure that any persisted objects have been deleted.
+<4> reach inside the Wicket viewer's internals to obtain the list of breadcrumbs.
+<5> loop over all breadcrumbs
+<6> unwrap the Wicket viewer's serializable representation of each domain object (`EntityModel`) to the Isis runtime's
+representation (`ObjectAdapter`)
+<7> unwrap the Isis runtime's representation of each domain object (`ObjectAdapter`) to the domain object pojo itself
+<8> if object is persistable (not a view model) then make sure it is not deleted
+<9> return the first object if any, otherwise the home page object (if any).
+
+Note that the above implementation uses Java 8, so if you are using Java 7 then you'll need to backport accordingly.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-to-implement-a-spellchecker.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-to-implement-a-spellchecker.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-to-implement-a-spellchecker.adoc
new file mode 100644
index 0000000..c141366
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-to-implement-a-spellchecker.adoc
@@ -0,0 +1,29 @@
+[[_dg_hints-and-tips_how-to-implement-a-spellchecker]]
+= How to implement a spellchecker?
+: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/
+
+
+
+From this link:http://isis.markmail.org/thread/dduarjscrbnodfsi[thread] on the Apache Isis users mailing list:
+
+* _What is the easiest way to add a spell checker to the text written in a field in
+   a domain object, for instance to check English syntax?_
+
+One way to implement is to use the xref:rgsvc.adoc#_rgsvc_api_EventBusService[event bus]:
+
+* Set up a xref:rgcsm.adoc#_rgcsm_classes_domainevent[domain event] xref:rgcsm.adoc#_rgcsm_classes_super_AbstractSubscriber[subscriber] that can veto the changes.
+
+* if the change is made through an action, you can use xref:rgant.adoc#_rgant-Action_domainEvent[`@Action#domainEvent()`].
+
+if if the change is made through an edit, you can use xref:rgant.adoc#_rgant-Property_domainEvent[`@Property#domainEvent()`].
+
+You'll need some way to know which fields should be spell checked.  Two ways spring to mind:
+
+* either look at the domain event's identifier
+
+* or subclass the domain event (recommended anyway) and have those subclass events implement some sort of marker interface, eg a `SpellCheckEvent`.
+
+And you'll (obviously) also need some sort of spell checker implementation to call.
+

http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_i18n-label-in-wicket-viewer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_i18n-label-in-wicket-viewer.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_i18n-label-in-wicket-viewer.adoc
new file mode 100644
index 0000000..22263cd
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_i18n-label-in-wicket-viewer.adoc
@@ -0,0 +1,26 @@
+[[_dg_hints-and-tips_i18n-label-in-wicket-viewer]]
+= How i18n the Wicket viewer?
+: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/
+
+
+
+From link:http://isis.markmail.org/thread/ctppmtcbsf4iskzi[this thread] on the Apache Isis users mailing list:
+
+* _I am trying to internationalize the label descriptions of form actions, eg those in `ActionParametersFormPanel`.
+Referencing those via their message id inside a .po file didn't work either.
+Can this be done?_
+
+
+The above FAQ was raised against `1.10.0`.  As of `1.11.0` (due to link:https://issues.apache.org/jira/browse/ISIS-1093[ISIS-1093]) it _is_ now possible to internationalize both the Wicket viewer's labels as well as the regular translations of the domain object metadata using the `.po` translation files as supported by the xref:rgsvc.adoc#_rgsvc_spi_TranslationService[`TranslationService`].
+
+Full details of the ``msgId``s that must be added to the `translations.po` file can be found in xref:guides/ugbtb.adoc#__ugbtb_i18n_wicket-viewer[i18n] section of the xref:ugbtb.adoc#[beyond the basics] guide.
+
+In prior releases (`1.10.0` and earlier) it was necessary to use link:https://ci.apache.org/projects/wicket/guide/6.x/guide/i18n.html#i18n_3[Wicket's internationalization support], namely resource bundles.  This is still supported (as a fallback):
+
+* create a directory structure inside the webapp resource folder following that pattern `org.apache.isis.viewer.wicket.ui.components.actions`
+
+* Inside there create an equivalent `ActionParametersFormPanel_xx_XX.properties` or `ActionParametersFormPanel_xx.properties` file for the various locales that you want to support (eg `ActionParametersFormPanel_en_UK.properties`, `ActionParametersFormPanel_en_US.properties`, `ActionParametersFormPanel_de.properties` and so on).
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_per-user-themes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_per-user-themes.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_per-user-themes.adoc
new file mode 100644
index 0000000..10a89f1
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_per-user-themes.adoc
@@ -0,0 +1,91 @@
+[[_dg_hints-and-tips_per-user-themes]]
+= Per-user Themes
+: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/
+
+
+From link:http://isis.markmail.org/thread/kb4442niwwbnghey[this thread] on the Apache Isis users mailing list:
+
+* _Is it possible to have each of our resellers (using our Isis application) use there own theme/branding with their own logo and colors?
+Would this also be possible for the login page, possibly depending on the used host name?_
+
+
+Yes, you can do this, by installing a custom implementation of the Wicket Bootstrap's `ActiveThemeProvider`.
+
+The http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] (non-ASF) actually link:https://github.com/isisaddons/isis-app-todoapp/tree/61b8114a8e01dbb3c380b31cf09eaed456407570[does this], storing the info via the http://github.com/isisaddons/isis-module-settings[Isis addons' settings module] settings modules:
+
+
+[source,java]
+.IActiveThemeProvider implementation
+----
+public class UserSettingsThemeProvider implements ActiveThemeProvider {
+    ...
+    @Override
+    public ITheme getActiveTheme() {
+        if(IsisContext.getSpecificationLoader().isInitialized()) {
+            final String themeName = IsisContext.doInSession(new Callable<String>() {
+                @Override
+                public String call() throws Exception {
+                    final UserSettingsService userSettingsService =
+                        lookupService(UserSettingsService.class);
+                    final UserSetting activeTheme = userSettingsService.find(
+                            IsisContext.getAuthenticationSession().getUserName(),
+                            ACTIVE_THEME);
+                    return activeTheme != null ? activeTheme.valueAsString() : null;
+                }
+            });
+            return themeFor(themeName);
+        }
+        return new SessionThemeProvider().getActiveTheme();
+    }
+    @Override
+    public void setActiveTheme(final String themeName) {
+        IsisContext.doInSession(new Runnable() {
+            @Override
+            public void run() {
+                final String currentUsrName =
+                    IsisContext.getAuthenticationSession().getUserName();
+                final UserSettingsServiceRW userSettingsService =
+                        lookupService(UserSettingsServiceRW.class);
+                final UserSettingJdo activeTheme =
+                        (UserSettingJdo) userSettingsService.find(
+                                                currentUsrName, ACTIVE_THEME);
+                if(activeTheme != null) {
+                    activeTheme.updateAsString(themeName);
+                } else {
+                    userSettingsService.newString(
+                        currentUsrName, ACTIVE_THEME, "Active Bootstrap theme for user", themeName);
+                }
+            }
+        });
+    }
+    private ITheme themeFor(final String themeName) {
+        final ThemeProvider themeProvider = settings.getThemeProvider();
+        if(themeName != null) {
+            for (final ITheme theme : themeProvider.available()) {
+                if (themeName.equals(theme.name()))
+                    return theme;
+            }
+        }
+        return themeProvider.defaultTheme();
+    }
+    ...
+}
+----
+
+and
+
+[source,java]
+.Using the ActiveThemeProvider
+----
+@Override
+protected void init() {
+    super.init();
+
+    final IBootstrapSettings settings = Bootstrap.getSettings();
+    settings.setThemeProvider(new BootswatchThemeProvider(BootswatchTheme.Flatly));
+
+    settings.setActiveThemeProvider(new UserSettingsThemeProvider(settings));
+}
+----

http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_restful-image-property.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_restful-image-property.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_restful-image-property.adoc
new file mode 100644
index 0000000..3084508
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_restful-image-property.adoc
@@ -0,0 +1,25 @@
+[[_dg_hints-and-tips_restful-image-property]]
+= How parse images in RO viewer?
+: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/
+
+
+From this link:http://markmail.org/message/4kcu7sml4ufdsah3[thread] on the Apache Isis users mailing list:
+
+* _I am trying to display an image in a JavaScript client app, the image comes from
+   an Isis RO web service as a string, but it won't show.
+Is there something I should do to change the message?_
+
+
+The RO viewer returns the image as a string, in the form:
+
+    "Tacos.jpg:image/jpeg:/9j//4AAQSkZJRgABAQEAlgCWAAD/  ...."
+
+This is in the form:
+
+    (filename):(mime type):(binary data in base64)
+
+This is basically the xref:rgcms.adoc#_rgcms_classes_value-types_Blob[`Blob`] value type, in string form.
+
+To use, split the parts then format the mime type and base64 data correctly before using as source in an `<img>` tag.

http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_subtype-entity-not-fully-populated.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_subtype-entity-not-fully-populated.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_subtype-entity-not-fully-populated.adoc
new file mode 100644
index 0000000..d5f5965
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_subtype-entity-not-fully-populated.adoc
@@ -0,0 +1,60 @@
+[[_dg_hints-and-tips_subtype-entity-not-fully-populated]]
+= Subtype not fully populated
+: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/
+
+
+Taken from link:http://markmail.org/message/ovgai56uqgfgnrx7[this thread] on the Apache Isis users mailing list...
+
+
+If it seems that Apache Isis (or rather DataNucleus) isn't fully populating domain entities (ie leaving some properties as `null`), then check that your actions are not accessing the fields directly.
+Use getters instead.
+
+
+[WARNING]
+====
+Properties of domain entities should always be accessed using getters.
+The only code that should access to fields should be the getters themselves.
+====
+
+Why so?
+Because DataNucleus will potentially lazy load some properties, but to do this it needs to know that the field is being requested.
+This is the purpose of the enhancement phase: the bytecode of the original getter method is actually wrapped in code that does the lazy loading checking.
+But hitting the field directly means that the lazy loading code does not run.
+
+This error can be subtle: sometimes "incorrect" code that accesses the fields will seem to work.
+But that will be because the field has been populated already, for whatever reason.
+
+One case where you will find the issue highlighted is for subtype tables that have been mapped using an inheritance strategy of `NEW_TABLE`, eg:
+
+[source,java]
+----
+@javax.jdo.annotations.PersistenceCapable
+@javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.NEW_TABLE)
+public class SupertypeEntity {
+    ...
+}
+----
+
+and then:
+
+[source,java]
+----
+@javax.jdo.annotations.PersistenceCapable
+@javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.NEW_TABLE)
+public class SubtypeEntity extends SupertypeEntity {
+    ...
+}
+----
+
+This will generate two tables in the database, with the primary key of the supertype table propagated as a foreign key (also primary key) of the subtype table (sometimes called "table per type" strategy).
+This means that DataNucleus might retrieve data from only the supertype table, and the lazily load the subtype fields only as required.
+This is preferable to doing a left outer join from the super- to the subtype tables to retrieve data that might not be needed.
+
+On the other hand, if the `SUPERCLASS_TABLE` strategy (aka "table per hierarchy" or roll-up) or the `SUBCLASS_TABLE` strategy (roll-down) was used, then the problem is less likely to occur because DataNucleus would obtain all the data for any given instance from a single table.
+
+Final note: references to other objects (either scalar references or in collections) in particular require that getters rather than fields to be used to obtain them: it's hopefully obvious that DataNucleus (like all ORMs) should not and will not resolve such references (otherwise, where to stop... and the whole database would be loaded into memory).
+
+In summary, there's just one rule: *always use the getters, never the fields*.
+

http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/dg/dg.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/dg.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/dg.adoc
index 5233145..76cd0a5 100644
--- a/adocs/documentation/src/main/asciidoc/guides/dg/dg.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/dg.adoc
@@ -51,9 +51,10 @@ The remaining guides are:
 
 
 
-
 include::_dg_ide.adoc[leveloffset=+1]
 
+include::_dg_hints-and-tips.adoc[leveloffset=+1]
+
 include::_dg_building-isis.adoc[leveloffset=+1]
 
 include::_dg_asciidoc.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs.adoc
deleted file mode 100644
index 1841474..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs.adoc
+++ /dev/null
@@ -1,21 +0,0 @@
-[[_ugfun_faqs]]
-= FAQs
-: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/
-
-
-This chapter has FAQs (with solutions) for problems we've encountered ourselves or have been raised on the
-Apache Isis mailing lists.
-
-See also xref:ugvro.adoc#_ugvro_hints-and-tips[Restful Objects hints-n-tips].
-
-include::_ugfun_faqs_enabling-logging.adoc[leveloffset=+1]
-include::_ugfun_faqs_subtype-entity-not-fully-populated.adoc[leveloffset=+1]
-include::_ugfun_faqs_restful-image-property.adoc[leveloffset=+1]
-include::_ugfun_faqs_enhance-only.adoc[leveloffset=+1]
-include::_ugfun_faqs_per-user-themes.adoc[leveloffset=+1]
-include::_ugfun_faqs_i18n-label-in-wicket-viewer.adoc[leveloffset=+1]
-include::_ugfun_faqs_how-to-handle-void-and-null-results.adoc[leveloffset=+1]
-include::_ugfun_faqs_how-to-implement-a-spellchecker.adoc[leveloffset=+1]
-include::_ugfun_faqs_how-run-fixtures-on-app-startup.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_enabling-logging.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_enabling-logging.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_enabling-logging.adoc
deleted file mode 100644
index 18e4a1f..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_enabling-logging.adoc
+++ /dev/null
@@ -1,41 +0,0 @@
-[[_ugfun_faqs_enabling-logging]]
-= 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/
-
-Sometimes you just need to see what is going on.
-There are various ways in which logging can be enabled, here are the ones we tend to use.
-
-* In Apache Isis +
-+
-Modify `WEB-INF/logging.properties` (a log4j config file)
-
-* In DataNucleus +
-+
-As per the http://www.datanucleus.org/products/accessplatform/logging.html[DN logging page]
-
-* In the JDBC Driver +
-+
-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:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
-
-* In the database +
-+
-Details below.
-
-
-Database logging can be configured:
-
-* for HSQLDB +
-+
-by adding`;sqllog=3` to the end of the JDBC URL.
-
-* for PostgreSQL: +
-+
-Can change `postgresql\9.2\data\postgresql.conf`; see link:http://www.postgresql.org/docs/9.2/static/runtime-config-logging.html[this article] for details.
-
-* for MS SQL Server Logging: +
-+
-We like to use the excellent SQL Profiler tool.
-

http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_enhance-only.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_enhance-only.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_enhance-only.adoc
deleted file mode 100644
index 4af2db6..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_enhance-only.adoc
+++ /dev/null
@@ -1,25 +0,0 @@
-[[_ugfun_faqs_enhance-only]]
-= Enhance only (IntelliJ)
-: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/
-
-
-From the Apache Isis mailing list is:
-
-* _Is there a simple way to make a run configuration in IntelliJ for running the datanucleus enhancer before running integration test?_
-
-Yes, you can; here's one way:
-
-* Duplicate your run configuration for running the webapp
-** the one where the main class is `org.apache.isis.WebServer`
-** there's a button for this on the run configurations dialog.
-* then, on your copy change the main class to `org.apache.isis.Dummy`
-
-Or, you could just write a small shell script and run from the command line:
-
-[source,bash]
-.enhance.sh
-----
-mvn -pl dom datanucleus:enhance -o
-----

http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_how-run-fixtures-on-app-startup.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_how-run-fixtures-on-app-startup.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_how-run-fixtures-on-app-startup.adoc
deleted file mode 100644
index 9964d39..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_how-run-fixtures-on-app-startup.adoc
+++ /dev/null
@@ -1,24 +0,0 @@
-[[_ugfun_faqs_how-run-fixtures-on-app-startup]]
-= How run fixtures on startup?
-: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/
-
-
-From this link:http://isis.markmail.org/thread/g6amfj2eyf2xfjbr[thread] on the Apache Isis users mailing list:
-
-* _my fixtures have grown into a couple of files the application needs to read in when it starts the first time (and possibly later on when the files content change).
-What is the right way to do this?
-Hook up into the webapp start?
-Use events?_
-
-
-The standard approach is to use xref:ugtst.adoc#_ugtst_fixture-scripts[fixture scripts].
-These can be run in on start-up typically by being specified in the xref:rgcsm.adoc#_rgcsm_classes_AppManifest-bootstrapping[`AppManifest`], see for
-example the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype].
-
-Alternatively just set "isis.fixtures" and "isis.persistor.datanucleus.install-fixtures" properties.
-
-In terms of implementations, you might also want to check out the (non-ASF) http://github.com/isisaddons/isis-module-excel[Isis addons' excel] module, by using link:https://github.com/isisaddons/isis-module-excel/blob/master/dom/src/main/java/org/isisaddons/module/excel/dom/ExcelFixture.java[`ExcelFixture`] and overriding `ExcelFixtureRowHandler` (same package).
-An example can be found in this (non ASF) link:https://github.com/incodehq/contactapp[contactapp], see link:https://github.com/incodehq/contactapp/blob/master/backend/fixture/src/main/java/domainapp/fixture/scenarios/demo/ContactRowHandler.java[`ContactRowHandler`].
-

http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_how-to-handle-void-and-null-results.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_how-to-handle-void-and-null-results.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_how-to-handle-void-and-null-results.adoc
deleted file mode 100644
index b57c453..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_how-to-handle-void-and-null-results.adoc
+++ /dev/null
@@ -1,79 +0,0 @@
-[[_ugfun_faqs_how-to-handle-void-and-null-results]]
-= How to handle void/null results
-: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/
-
-
-
-From this link:http://isis.markmail.org/thread/yf7qdeiu3vrvk2ei[thread] on the Apache Isis users mailing list:
-
-* _When using a `void` action, let\u2019s say a remove action, the user is redirected to a
-page "no results".
-When clicking the back button in the browser the user sees "Object not found" (since you\u2019ve just deleted this object)._
-
-* _You can return a list for example to prevent the user from being redirect to a
-  "No results" page, but I think it\u2019s not the responsibility of the controllers in
-  the domain model._
-
-* _A solution could be that wicket viewer goes back one page when
-  encountering a deleted object.
-And refresh the current page when receiving a null response or invoking a void action.
-But how to implement this?_
-
-One way to implement this idea is to provide a custom implementation of the xref:rgsvc.adoc#_rgsvc_spi_RoutingService[`RoutingService`] SPI domain service.
-The default implementation will either return the current object (if not null), else the home page (as defined by xref:rgant.adoc#_rgant-HomePage[`@HomePage`]) if one exists.
-
-The following custom implementation refines this to use the breadcrumbs (available in the Wicket viewer) to return the first non-deleted domain object found in the list of breadcrumbs:
-
-[source,java]
-----
-@DomainService(nature = NatureOfService.DOMAIN)
-@DomainServiceLayout(menuOrder = "1")                                           // <1>
-public class RoutingServiceUsingBreadcrumbs extends RoutingServiceDefault {
-    @Override
-    public Object route(final Object original) {
-        if(original != null) {                                                  // <2>
-            return original;
-        }
-        container.flush();                                                      // <3>
-
-        final BreadcrumbModelProvider wicketSession =                           // <4>
-            (BreadcrumbModelProvider) AuthenticatedWebSession.get();
-        final BreadcrumbModel breadcrumbModel =
-            wicketSession.getBreadcrumbModel();
-        final List<EntityModel> breadcrumbs = breadcrumbModel.getList();
-
-        final Optional<Object> firstViewModelOrNonDeletedPojoIfAny =
-                breadcrumbs.stream()                                            // <5>
-                .filter(entityModel -> entityModel != null)
-                .map(EntityModel::getObject)                                    // <6>
-                .filter(objectAdapter -> objectAdapter != null)
-                .map(ObjectAdapter::getObject)                                  // <7>
-                .filter(pojo -> !(pojo instanceof Persistable) ||
-                                !((Persistable)pojo).dnIsDeleted())             // <8>
-                .findFirst();
-
-        return firstViewModelOrNonDeletedPojoIfAny.orElse(homePage());          // <9>
-    }
-    private Object homePage() {
-        return homePageProviderService.homePage();
-    }
-    @Inject
-    HomePageProviderService homePageProviderService;
-    @Inject
-    DomainObjectContainer container;
-}
-----
-<1> override the default imlpementation
-<2> if a non-null object was returned, then return this
-<3> ensure that any persisted objects have been deleted.
-<4> reach inside the Wicket viewer's internals to obtain the list of breadcrumbs.
-<5> loop over all breadcrumbs
-<6> unwrap the Wicket viewer's serializable representation of each domain object (`EntityModel`) to the Isis runtime's
-representation (`ObjectAdapter`)
-<7> unwrap the Isis runtime's representation of each domain object (`ObjectAdapter`) to the domain object pojo itself
-<8> if object is persistable (not a view model) then make sure it is not deleted
-<9> return the first object if any, otherwise the home page object (if any).
-
-Note that the above implementation uses Java 8, so if you are using Java 7 then you'll need to backport accordingly.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_how-to-implement-a-spellchecker.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_how-to-implement-a-spellchecker.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_how-to-implement-a-spellchecker.adoc
deleted file mode 100644
index 1c48c0d..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_how-to-implement-a-spellchecker.adoc
+++ /dev/null
@@ -1,29 +0,0 @@
-[[_ugfun_faqs_how-to-implement-a-spellchecker]]
-= How to implement a spellchecker?
-: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/
-
-
-
-From this link:http://isis.markmail.org/thread/dduarjscrbnodfsi[thread] on the Apache Isis users mailing list:
-
-* _What is the easiest way to add a spell checker to the text written in a field in
-   a domain object, for instance to check English syntax?_
-
-One way to implement is to use the xref:rgsvc.adoc#_rgsvc_api_EventBusService[event bus]:
-
-* Set up a xref:rgcsm.adoc#_rgcsm_classes_domainevent[domain event] xref:rgcsm.adoc#_rgcsm_classes_super_AbstractSubscriber[subscriber] that can veto the changes.
-
-* if the change is made through an action, you can use xref:rgant.adoc#_rgant-Action_domainEvent[`@Action#domainEvent()`].
-
-if if the change is made through an edit, you can use xref:rgant.adoc#_rgant-Property_domainEvent[`@Property#domainEvent()`].
-
-You'll need some way to know which fields should be spell checked.  Two ways spring to mind:
-
-* either look at the domain event's identifier
-
-* or subclass the domain event (recommended anyway) and have those subclass events implement some sort of marker interface, eg a `SpellCheckEvent`.
-
-And you'll (obviously) also need some sort of spell checker implementation to call.
-

http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_i18n-label-in-wicket-viewer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_i18n-label-in-wicket-viewer.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_i18n-label-in-wicket-viewer.adoc
deleted file mode 100644
index 220c58b..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_i18n-label-in-wicket-viewer.adoc
+++ /dev/null
@@ -1,26 +0,0 @@
-[[_ugfun_faqs_i18n-label-in-wicket-viewer]]
-= How i18n the Wicket viewer?
-: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/
-
-
-
-From link:http://isis.markmail.org/thread/ctppmtcbsf4iskzi[this thread] on the Apache Isis users mailing list:
-
-* _I am trying to internationalize the label descriptions of form actions, eg those in `ActionParametersFormPanel`.
-Referencing those via their message id inside a .po file didn't work either.
-Can this be done?_
-
-
-The above FAQ was raised against `1.10.0`.  As of `1.11.0` (due to link:https://issues.apache.org/jira/browse/ISIS-1093[ISIS-1093]) it _is_ now possible to internationalize both the Wicket viewer's labels as well as the regular translations of the domain object metadata using the `.po` translation files as supported by the xref:rgsvc.adoc#_rgsvc_spi_TranslationService[`TranslationService`].
-
-Full details of the ``msgId``s that must be added to the `translations.po` file can be found in xref:guides/ugbtb.adoc#__ugbtb_i18n_wicket-viewer[i18n] section of the xref:ugbtb.adoc#[beyond the basics] guide.
-
-In prior releases (`1.10.0` and earlier) it was necessary to use link:https://ci.apache.org/projects/wicket/guide/6.x/guide/i18n.html#i18n_3[Wicket's internationalization support], namely resource bundles.  This is still supported (as a fallback):
-
-* create a directory structure inside the webapp resource folder following that pattern `org.apache.isis.viewer.wicket.ui.components.actions`
-
-* Inside there create an equivalent `ActionParametersFormPanel_xx_XX.properties` or `ActionParametersFormPanel_xx.properties` file for the various locales that you want to support (eg `ActionParametersFormPanel_en_UK.properties`, `ActionParametersFormPanel_en_US.properties`, `ActionParametersFormPanel_de.properties` and so on).
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_per-user-themes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_per-user-themes.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_per-user-themes.adoc
deleted file mode 100644
index a9b34d4..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_per-user-themes.adoc
+++ /dev/null
@@ -1,91 +0,0 @@
-[[_ugfun_faqs_per-user-themes]]
-= Per-user Themes
-: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/
-
-
-From link:http://isis.markmail.org/thread/kb4442niwwbnghey[this thread] on the Apache Isis users mailing list:
-
-* _Is it possible to have each of our resellers (using our Isis application) use there own theme/branding with their own logo and colors?
-Would this also be possible for the login page, possibly depending on the used host name?_
-
-
-Yes, you can do this, by installing a custom implementation of the Wicket Bootstrap's `ActiveThemeProvider`.
-
-The http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] (non-ASF) actually link:https://github.com/isisaddons/isis-app-todoapp/tree/61b8114a8e01dbb3c380b31cf09eaed456407570[does this], storing the info via the http://github.com/isisaddons/isis-module-settings[Isis addons' settings module] settings modules:
-
-
-[source,java]
-.IActiveThemeProvider implementation
-----
-public class UserSettingsThemeProvider implements ActiveThemeProvider {
-    ...
-    @Override
-    public ITheme getActiveTheme() {
-        if(IsisContext.getSpecificationLoader().isInitialized()) {
-            final String themeName = IsisContext.doInSession(new Callable<String>() {
-                @Override
-                public String call() throws Exception {
-                    final UserSettingsService userSettingsService =
-                        lookupService(UserSettingsService.class);
-                    final UserSetting activeTheme = userSettingsService.find(
-                            IsisContext.getAuthenticationSession().getUserName(),
-                            ACTIVE_THEME);
-                    return activeTheme != null ? activeTheme.valueAsString() : null;
-                }
-            });
-            return themeFor(themeName);
-        }
-        return new SessionThemeProvider().getActiveTheme();
-    }
-    @Override
-    public void setActiveTheme(final String themeName) {
-        IsisContext.doInSession(new Runnable() {
-            @Override
-            public void run() {
-                final String currentUsrName =
-                    IsisContext.getAuthenticationSession().getUserName();
-                final UserSettingsServiceRW userSettingsService =
-                        lookupService(UserSettingsServiceRW.class);
-                final UserSettingJdo activeTheme =
-                        (UserSettingJdo) userSettingsService.find(
-                                                currentUsrName, ACTIVE_THEME);
-                if(activeTheme != null) {
-                    activeTheme.updateAsString(themeName);
-                } else {
-                    userSettingsService.newString(
-                        currentUsrName, ACTIVE_THEME, "Active Bootstrap theme for user", themeName);
-                }
-            }
-        });
-    }
-    private ITheme themeFor(final String themeName) {
-        final ThemeProvider themeProvider = settings.getThemeProvider();
-        if(themeName != null) {
-            for (final ITheme theme : themeProvider.available()) {
-                if (themeName.equals(theme.name()))
-                    return theme;
-            }
-        }
-        return themeProvider.defaultTheme();
-    }
-    ...
-}
-----
-
-and
-
-[source,java]
-.Using the ActiveThemeProvider
-----
-@Override
-protected void init() {
-    super.init();
-
-    final IBootstrapSettings settings = Bootstrap.getSettings();
-    settings.setThemeProvider(new BootswatchThemeProvider(BootswatchTheme.Flatly));
-
-    settings.setActiveThemeProvider(new UserSettingsThemeProvider(settings));
-}
-----

http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_restful-image-property.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_restful-image-property.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_restful-image-property.adoc
deleted file mode 100644
index e5deed8..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_restful-image-property.adoc
+++ /dev/null
@@ -1,25 +0,0 @@
-[[_ugfun_faqs_restful-image-property]]
-= How parse images in RO viewer?
-: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/
-
-
-From this link:http://markmail.org/message/4kcu7sml4ufdsah3[thread] on the Apache Isis users mailing list:
-
-* _I am trying to display an image in a JavaScript client app, the image comes from
-   an Isis RO web service as a string, but it won't show.
-Is there something I should do to change the message?_
-
-
-The RO viewer returns the image as a string, in the form:
-
-    "Tacos.jpg:image/jpeg:/9j//4AAQSkZJRgABAQEAlgCWAAD/  ...."
-
-This is in the form:
-
-    (filename):(mime type):(binary data in base64)
-
-This is basically the xref:rgcms.adoc#_rgcms_classes_value-types_Blob[`Blob`] value type, in string form.
-
-To use, split the parts then format the mime type and base64 data correctly before using as source in an `<img>` tag.

http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_subtype-entity-not-fully-populated.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_subtype-entity-not-fully-populated.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_subtype-entity-not-fully-populated.adoc
deleted file mode 100644
index 5b02ae0..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_subtype-entity-not-fully-populated.adoc
+++ /dev/null
@@ -1,60 +0,0 @@
-[[_ugfun_faqs_subtype-entity-not-fully-populated]]
-= Subtype not fully populated
-: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/
-
-
-Taken from link:http://markmail.org/message/ovgai56uqgfgnrx7[this thread] on the Apache Isis users mailing list...
-
-
-If it seems that Apache Isis (or rather DataNucleus) isn't fully populating domain entities (ie leaving some properties as `null`), then check that your actions are not accessing the fields directly.
-Use getters instead.
-
-
-[WARNING]
-====
-Properties of domain entities should always be accessed using getters.
-The only code that should access to fields should be the getters themselves.
-====
-
-Why so?
-Because DataNucleus will potentially lazy load some properties, but to do this it needs to know that the field is being requested.
-This is the purpose of the enhancement phase: the bytecode of the original getter method is actually wrapped in code that does the lazy loading checking.
-But hitting the field directly means that the lazy loading code does not run.
-
-This error can be subtle: sometimes "incorrect" code that accesses the fields will seem to work.
-But that will be because the field has been populated already, for whatever reason.
-
-One case where you will find the issue highlighted is for subtype tables that have been mapped using an inheritance strategy of `NEW_TABLE`, eg:
-
-[source,java]
-----
-@javax.jdo.annotations.PersistenceCapable
-@javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.NEW_TABLE)
-public class SupertypeEntity {
-    ...
-}
-----
-
-and then:
-
-[source,java]
-----
-@javax.jdo.annotations.PersistenceCapable
-@javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.NEW_TABLE)
-public class SubtypeEntity extends SupertypeEntity {
-    ...
-}
-----
-
-This will generate two tables in the database, with the primary key of the supertype table propagated as a foreign key (also primary key) of the subtype table (sometimes called "table per type" strategy).
-This means that DataNucleus might retrieve data from only the supertype table, and the lazily load the subtype fields only as required.
-This is preferable to doing a left outer join from the super- to the subtype tables to retrieve data that might not be needed.
-
-On the other hand, if the `SUPERCLASS_TABLE` strategy (aka "table per hierarchy" or roll-up) or the `SUBCLASS_TABLE` strategy (roll-down) was used, then the problem is less likely to occur because DataNucleus would obtain all the data for any given instance from a single table.
-
-Final note: references to other objects (either scalar references or in collections) in particular require that getters rather than fields to be used to obtain them: it's hopefully obvious that DataNucleus (like all ORMs) should not and will not resolve such references (otherwise, where to stop... and the whole database would be loaded into memory).
-
-In summary, there's just one rule: *always use the getters, never the fields*.
-

http://git-wip-us.apache.org/repos/asf/isis/blob/0c22c0a3/adocs/documentation/src/main/asciidoc/guides/ugfun/ugfun.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/ugfun.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/ugfun.adoc
index f119338..1379b7a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/ugfun.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/ugfun.adoc
@@ -14,7 +14,7 @@ and tells you how to xref:ugfun.adoc#_ugfun_getting-started[get started] with a
 
 It also describes a number of xref:ugfun.adoc#_ugfun_how-tos[how-to]s, describes how to influence the
 xref:ugvw.adoc#_ugvw_layout[UI layout] of your domain objects (this is ultimately just a type of metadata), and it
- catalogues various xref:ugfun.adoc#_ugfun_faqs.adoc[FAQ]s.
+ catalogues various xref:dg.adoc#_dg_hints-and-tips.adoc[FAQ]s.
 
 === Other Guides
 

[15/58] [abbrv] isis git commit: ISIS-1521: fixes xref links between guides

[da...@apache.org]

ISIS-1521: fixes xref links between guides


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/252c2f8e
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/252c2f8e
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/252c2f8e

Branch: refs/heads/wip
Commit: 252c2f8eaf89038b604120018df7faa1fa8e7559
Parents: 0c22c0a
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Fri Apr 14 15:27:41 2017 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Thu Apr 20 09:09:29 2017 +0100

----------------------------------------------------------------------
 .../_cgcom_asciidoc-publish-procedure.adoc      |   4 +-
 .../guides/cgcom/_cgcom_cutting-a-release.adoc  |  18 +--
 .../cgcom/_cgcom_policies_git-policy.adoc       |   2 +-
 .../cgcom/_cgcom_post-release-successful.adoc   |  12 +-
 .../cgcom/_cgcom_post-release-unsuccessful.adoc |   6 +-
 ...om_release-process-for-interim-releases.adoc |   2 +-
 .../cgcom/_cgcom_release-process-prereqs.adoc   |   4 +-
 .../guides/cgcom/_cgcom_verifying-releases.adoc |  14 +--
 .../guides/dg/_dg_asciidoc-templates.adoc       |  72 +++++------
 .../main/asciidoc/guides/dg/_dg_asciidoc.adoc   |   4 +-
 .../dg/_dg_asciidoc_publish-procedure.adoc      |   2 +-
 .../dg/_dg_asciidoc_writing-the-docs.adoc       |   4 +-
 .../asciidoc/guides/dg/_dg_building-isis.adoc   |   2 +-
 .../asciidoc/guides/dg/_dg_contributing.adoc    |   4 +-
 .../asciidoc/guides/dg/_dg_git-cookbook.adoc    |   8 +-
 .../dg/_dg_hints-and-tips_enabling-logging.adoc |   2 +-
 ...ips_how-to-handle-void-and-null-results.adoc |   4 +-
 ...nd-tips_how-to-implement-a-spellchecker.adoc |   6 +-
 ...ts-and-tips_i18n-label-in-wicket-viewer.adoc |   2 +-
 ...g_hints-and-tips_restful-image-property.adoc |   2 +-
 .../asciidoc/guides/dg/_dg_ide_eclipse.adoc     |   6 +-
 .../asciidoc/guides/dg/_dg_ide_intellij.adoc    |   6 +-
 .../asciidoc/guides/dg/_dg_project-lombok.adoc  |   4 +-
 .../src/main/asciidoc/guides/dg/dg.adoc         |  12 +-
 .../asciidoc/guides/rgant/_rgant-Action.adoc    |  26 ++--
 .../guides/rgant/_rgant-ActionLayout.adoc       |  24 ++--
 .../rgant/_rgant-ActionLayout_bookmarking.adoc  |   4 +-
 .../_rgant-ActionLayout_contributedAs.adoc      |   4 +-
 .../rgant/_rgant-ActionLayout_cssClass.adoc     |   6 +-
 .../rgant/_rgant-ActionLayout_cssClassFa.adoc   |   4 +-
 .../rgant/_rgant-ActionLayout_describedAs.adoc  |   2 +-
 .../rgant/_rgant-ActionLayout_hidden.adoc       |   6 +-
 .../guides/rgant/_rgant-ActionLayout_named.adoc |   2 +-
 .../rgant/_rgant-ActionLayout_position.adoc     |   2 +-
 .../guides/rgant/_rgant-Action_command.adoc     |  20 ++--
 .../guides/rgant/_rgant-Action_domainEvent.adoc |  12 +-
 .../guides/rgant/_rgant-Action_hidden.adoc      |   6 +-
 .../guides/rgant/_rgant-Action_publishing.adoc  |  14 +--
 .../guides/rgant/_rgant-Action_restrictTo.adoc  |   2 +-
 .../guides/rgant/_rgant-Action_semantics.adoc   |   2 +-
 .../guides/rgant/_rgant-Action_typeOf.adoc      |   2 +-
 .../guides/rgant/_rgant-Collection.adoc         |  14 +--
 .../guides/rgant/_rgant-CollectionLayout.adoc   |  20 ++--
 .../rgant/_rgant-CollectionLayout_cssClass.adoc |   4 +-
 .../_rgant-CollectionLayout_defaultView.adoc    |   2 +-
 .../_rgant-CollectionLayout_describedAs.adoc    |   2 +-
 .../rgant/_rgant-CollectionLayout_hidden.adoc   |   4 +-
 .../rgant/_rgant-CollectionLayout_named.adoc    |   2 +-
 .../rgant/_rgant-CollectionLayout_paged.adoc    |   4 +-
 .../rgant/_rgant-CollectionLayout_render.adoc   |   4 +-
 .../rgant/_rgant-Collection_domainEvent.adoc    |  14 +--
 .../guides/rgant/_rgant-Collection_editing.adoc |  10 +-
 .../guides/rgant/_rgant-Collection_hidden.adoc  |   4 +-
 .../rgant/_rgant-Collection_notPersisted.adoc   |   2 +-
 .../guides/rgant/_rgant-Collection_typeOf.adoc  |   2 +-
 .../asciidoc/guides/rgant/_rgant-Column.adoc    |  10 +-
 .../asciidoc/guides/rgant/_rgant-Digits.adoc    |   2 +-
 .../guides/rgant/_rgant-Discriminator.adoc      |  10 +-
 .../guides/rgant/_rgant-DomainObject.adoc       |  46 +++----
 .../guides/rgant/_rgant-DomainObjectLayout.adoc |  30 ++---
 .../_rgant-DomainObjectLayout_bookmarking.adoc  |   2 +-
 .../_rgant-DomainObjectLayout_cssClass.adoc     |   6 +-
 .../_rgant-DomainObjectLayout_cssClassFa.adoc   |   6 +-
 ...gant-DomainObjectLayout_cssClassUiEvent.adoc |  12 +-
 .../_rgant-DomainObjectLayout_describedAs.adoc  |   2 +-
 .../_rgant-DomainObjectLayout_iconUiEvent.adoc  |  12 +-
 .../rgant/_rgant-DomainObjectLayout_named.adoc  |   4 +-
 .../rgant/_rgant-DomainObjectLayout_paged.adoc  |   4 +-
 .../rgant/_rgant-DomainObjectLayout_plural.adoc |   2 +-
 .../_rgant-DomainObjectLayout_titleUiEvent.adoc |  14 +--
 .../rgant/_rgant-DomainObject_auditing.adoc     |   4 +-
 ...ant-DomainObject_autoCompleteRepository.adoc |   6 +-
 .../rgant/_rgant-DomainObject_bounded.adoc      |   2 +-
 ...gant-DomainObject_createdLifecycleEvent.adoc |   8 +-
 .../rgant/_rgant-DomainObject_editing.adoc      |   2 +-
 ...rgant-DomainObject_loadedLifecycleEvent.adoc |   4 +-
 .../rgant/_rgant-DomainObject_nature.adoc       |   4 +-
 .../rgant/_rgant-DomainObject_objectType.adoc   |  12 +-
 ...nt-DomainObject_persistedLifecycleEvent.adoc |   4 +-
 ...t-DomainObject_persistingLifecycleEvent.adoc |   6 +-
 .../rgant/_rgant-DomainObject_publishing.adoc   |  14 +--
 ...ant-DomainObject_removingLifecycleEvent.adoc |   6 +-
 ...gant-DomainObject_updatedLifecycleEvent.adoc |   4 +-
 ...ant-DomainObject_updatingLifecycleEvent.adoc |   6 +-
 .../guides/rgant/_rgant-DomainService.adoc      |  10 +-
 .../rgant/_rgant-DomainServiceLayout.adoc       |   6 +-
 .../_rgant-DomainServiceLayout_menuBar.adoc     |   2 +-
 .../_rgant-DomainServiceLayout_menuOrder.adoc   |   4 +-
 .../rgant/_rgant-DomainServiceLayout_named.adoc |   4 +-
 .../rgant/_rgant-DomainService_nature.adoc      |   4 +-
 .../rgant/_rgant-DomainService_objectType.adoc  |   6 +-
 .../_rgant-DomainService_repositoryFor.adoc     |   2 +-
 .../asciidoc/guides/rgant/_rgant-Inject.adoc    |   8 +-
 .../guides/rgant/_rgant-MemberGroupLayout.adoc  |   4 +-
 .../guides/rgant/_rgant-MemberOrder.adoc        |   6 +-
 .../asciidoc/guides/rgant/_rgant-MinLength.adoc |   2 +-
 .../asciidoc/guides/rgant/_rgant-Mixin.adoc     |   4 +-
 .../asciidoc/guides/rgant/_rgant-Nullable.adoc  |  12 +-
 .../asciidoc/guides/rgant/_rgant-Parameter.adoc |  18 +--
 .../guides/rgant/_rgant-ParameterLayout.adoc    |  20 ++--
 .../rgant/_rgant-ParameterLayout_cssClass.adoc  |   4 +-
 .../_rgant-ParameterLayout_describedAs.adoc     |   2 +-
 .../_rgant-ParameterLayout_labelPosition.adoc   |   6 +-
 .../rgant/_rgant-ParameterLayout_multiLine.adoc |   4 +-
 .../rgant/_rgant-ParameterLayout_named.adoc     |   4 +-
 ...ant-ParameterLayout_renderedAsDayBefore.adoc |   2 +-
 .../_rgant-ParameterLayout_typicalLength.adoc   |   2 +-
 .../rgant/_rgant-Parameter_fileAccept.adoc      |   6 +-
 .../rgant/_rgant-Parameter_maxLength.adoc       |   2 +-
 .../rgant/_rgant-Parameter_mustSatisfy.adoc     |   4 +-
 .../rgant/_rgant-Parameter_optionality.adoc     |   4 +-
 .../rgant/_rgant-Parameter_regexPattern.adoc    |   2 +-
 .../guides/rgant/_rgant-PersistenceCapable.adoc |  10 +-
 .../guides/rgant/_rgant-PostConstruct.adoc      |  16 +--
 .../guides/rgant/_rgant-PreDestroy.adoc         |  10 +-
 .../guides/rgant/_rgant-PrimaryKey.adoc         |   2 +-
 .../guides/rgant/_rgant-Programmatic.adoc       |   2 +-
 .../asciidoc/guides/rgant/_rgant-Property.adoc  |  30 ++---
 .../guides/rgant/_rgant-PropertyLayout.adoc     |  26 ++--
 .../rgant/_rgant-PropertyLayout_cssClass.adoc   |   4 +-
 .../_rgant-PropertyLayout_describedAs.adoc      |   2 +-
 .../rgant/_rgant-PropertyLayout_hidden.adoc     |   6 +-
 .../_rgant-PropertyLayout_labelPosition.adoc    |   6 +-
 .../rgant/_rgant-PropertyLayout_multiLine.adoc  |   4 +-
 .../rgant/_rgant-PropertyLayout_named.adoc      |   2 +-
 ...gant-PropertyLayout_renderedAsDayBefore.adoc |   2 +-
 .../_rgant-PropertyLayout_typicalLength.adoc    |   2 +-
 .../rgant/_rgant-Property_domainEvent.adoc      |  10 +-
 .../guides/rgant/_rgant-Property_editing.adoc   |   8 +-
 .../rgant/_rgant-Property_fileAccept.adoc       |   6 +-
 .../guides/rgant/_rgant-Property_hidden.adoc    |   6 +-
 .../guides/rgant/_rgant-Property_maxLength.adoc |   4 +-
 .../rgant/_rgant-Property_mustSatisfy.adoc      |   4 +-
 .../rgant/_rgant-Property_notPersisted.adoc     |   2 +-
 .../rgant/_rgant-Property_optionality.adoc      |   8 +-
 .../rgant/_rgant-Property_publishing.adoc       |  10 +-
 .../rgant/_rgant-Property_regexPattern.adoc     |   2 +-
 .../guides/rgant/_rgant-RequestScoped.adoc      |   4 +-
 .../asciidoc/guides/rgant/_rgant-Title.adoc     |   2 +-
 .../asciidoc/guides/rgant/_rgant-ViewModel.adoc |   8 +-
 .../guides/rgant/_rgant-ViewModelLayout.adoc    |  20 ++--
 .../rgant/_rgant-ViewModelLayout_cssClass.adoc  |   6 +-
 .../_rgant-ViewModelLayout_cssClassFa.adoc      |   6 +-
 .../_rgant-ViewModelLayout_describedAs.adoc     |   2 +-
 .../rgant/_rgant-ViewModelLayout_named.adoc     |   2 +-
 .../rgant/_rgant-ViewModelLayout_paged.adoc     |   4 +-
 .../rgant/_rgant-ViewModelLayout_plural.adoc    |   2 +-
 .../rgant/_rgant-ViewModel_objectType.adoc      |  12 +-
 .../guides/rgant/_rgant-XmlJavaTypeAdapter.adoc |   2 +-
 .../guides/rgant/_rgant-XmlRootElement.adoc     |  14 +--
 .../guides/rgant/_rgant_aaa_deprecated.adoc     | 102 ++++++++--------
 .../asciidoc/guides/rgant/_rgant_aaa_jdo.adoc   |  14 +--
 .../asciidoc/guides/rgant/_rgant_aaa_jee.adoc   |  22 ++--
 .../asciidoc/guides/rgant/_rgant_aaa_main.adoc  |  28 ++---
 .../asciidoc/guides/rgant/_rgant_aaa_other.adoc |  12 +-
 .../guides/rgcfg/_rgcfg_configuring-core.adoc   |  78 ++++++------
 .../guides/rgcfg/_rgcfg_deployment-types.adoc   |   2 +-
 .../rgcfg/_rgcfg_specifying-components.adoc     |  10 +-
 .../asciidoc/guides/rgcms/_rgcms_classes.adoc   |   2 +-
 ...rgcms_classes_AppManifest-bootstrapping.adoc |   6 +-
 ...ms_classes_contributee_HasTransactionId.adoc |   2 +-
 .../rgcms/_rgcms_classes_domainevent.adoc       |  12 +-
 ...classes_domainevent_AbstractDomainEvent.adoc |   6 +-
 ...s_classes_domainevent_ActionDomainEvent.adoc |   8 +-
 ...asses_domainevent_CollectionDomainEvent.adoc |   4 +-
 ...classes_domainevent_PropertyDomainEvent.adoc |   4 +-
 .../guides/rgcms/_rgcms_classes_layout.adoc     |  12 +-
 .../rgcms/_rgcms_classes_lifecycleevent.adoc    |  28 ++---
 ...s_lifecycleevent_AbstractLifecycleEvent.adoc |  14 +--
 ...asses_lifecycleevent_ObjectCreatedEvent.adoc |   4 +-
 ...lasses_lifecycleevent_ObjectLoadedEvent.adoc |   2 +-
 ...ses_lifecycleevent_ObjectPersistedEvent.adoc |   4 +-
 ...es_lifecycleevent_ObjectPersistingEvent.adoc |   4 +-
 ...sses_lifecycleevent_ObjectRemovingEvent.adoc |   4 +-
 ...asses_lifecycleevent_ObjectUpdatedEvent.adoc |   4 +-
 ...sses_lifecycleevent_ObjectUpdatingEvent.adoc |   4 +-
 .../guides/rgcms/_rgcms_classes_mixins_Dto.adoc |  12 +-
 .../rgcms/_rgcms_classes_mixins_Object.adoc     |  14 +--
 .../_rgcms_classes_mixins_Persistable.adoc      |   8 +-
 .../_rgcms_classes_roles_HoldsUpdatedAt.adoc    |   4 +-
 .../_rgcms_classes_roles_HoldsUpdatedBy.adoc    |   2 +-
 .../_rgcms_classes_roles_Timestampable.adoc     |   4 +-
 .../guides/rgcms/_rgcms_classes_spec.adoc       |   4 +-
 .../guides/rgcms/_rgcms_classes_super.adoc      |  18 +--
 ...s_classes_super_AbstractContainedObject.adoc |   4 +-
 ...gcms_classes_super_AbstractDomainObject.adoc |   4 +-
 ...sses_super_AbstractFactoryAndRepository.adoc |   4 +-
 .../_rgcms_classes_super_AbstractService.adoc   |   4 +-
 ..._rgcms_classes_super_AbstractSubscriber.adoc |  10 +-
 .../_rgcms_classes_super_AbstractViewModel.adoc |   4 +-
 .../_rgcms_classes_super_FixtureScripts.adoc    |   6 +-
 .../guides/rgcms/_rgcms_classes_uievent.adoc    |  16 +--
 .../_rgcms_classes_uievent_CssClassUiEvent.adoc |   2 +-
 .../_rgcms_classes_uievent_IconUiEvent.adoc     |   4 +-
 .../_rgcms_classes_uievent_TitleUiEvent.adoc    |   4 +-
 .../_rgcms_classes_utility_TitleBuffer.adoc     |   2 +-
 .../rgcms/_rgcms_classes_value-types_Blob.adoc  |   2 +-
 .../rgcms/_rgcms_classes_value-types_Clob.adoc  |   2 +-
 .../asciidoc/guides/rgcms/_rgcms_methods.adoc   |   2 +-
 .../guides/rgcms/_rgcms_methods_lifecycle.adoc  |  30 ++---
 .../rgcms/_rgcms_methods_lifecycle_created.adoc |   4 +-
 .../rgcms/_rgcms_methods_lifecycle_jdo-api.adoc |   4 +-
 .../rgcms/_rgcms_methods_lifecycle_loaded.adoc  |   2 +-
 .../_rgcms_methods_lifecycle_persisted.adoc     |   4 +-
 .../_rgcms_methods_lifecycle_persisting.adoc    |   4 +-
 .../rgcms/_rgcms_methods_lifecycle_removed.adoc |   4 +-
 .../_rgcms_methods_lifecycle_removing.adoc      |   4 +-
 .../rgcms/_rgcms_methods_lifecycle_updated.adoc |   4 +-
 .../_rgcms_methods_lifecycle_updating.adoc      |   4 +-
 .../guides/rgcms/_rgcms_methods_prefixes.adoc   |  50 ++++----
 .../rgcms/_rgcms_methods_prefixes_addTo.adoc    |   2 +-
 .../_rgcms_methods_prefixes_autoComplete.adoc   |   6 +-
 .../rgcms/_rgcms_methods_prefixes_choices.adoc  |   4 +-
 .../rgcms/_rgcms_methods_prefixes_clear.adoc    |   2 +-
 .../rgcms/_rgcms_methods_prefixes_default.adoc  |   6 +-
 .../rgcms/_rgcms_methods_prefixes_disable.adoc  |   2 +-
 .../rgcms/_rgcms_methods_prefixes_get.adoc      |   2 +-
 .../rgcms/_rgcms_methods_prefixes_hide.adoc     |   4 +-
 .../rgcms/_rgcms_methods_prefixes_modify.adoc   |   2 +-
 .../_rgcms_methods_prefixes_removeFrom.adoc     |   2 +-
 .../rgcms/_rgcms_methods_prefixes_set.adoc      |   2 +-
 .../_rgcms_methods_prefixes_validateAddTo.adoc  |   2 +-
 ...cms_methods_prefixes_validateRemoveFrom.adoc |   2 +-
 .../guides/rgcms/_rgcms_methods_reserved.adoc   |  22 ++--
 .../rgcms/_rgcms_methods_reserved_cssClass.adoc |   6 +-
 .../rgcms/_rgcms_methods_reserved_disable.adoc  |   4 +-
 .../rgcms/_rgcms_methods_reserved_getId.adoc    |   8 +-
 .../rgcms/_rgcms_methods_reserved_hide.adoc     |   6 +-
 .../rgcms/_rgcms_methods_reserved_iconName.adoc |   2 +-
 .../rgcms/_rgcms_methods_reserved_title.adoc    |   8 +-
 .../guides/rgcms/_rgcms_schema-aim.adoc         |  10 +-
 .../guides/rgcms/_rgcms_schema-chg.adoc         |  12 +-
 .../guides/rgcms/_rgcms_schema-cmd.adoc         |  12 +-
 .../guides/rgcms/_rgcms_schema-common.adoc      |  24 ++--
 .../guides/rgcms/_rgcms_schema-ixn.adoc         |  28 ++---
 .../asciidoc/guides/rgcms/_rgcms_schema.adoc    |  10 +-
 .../src/main/asciidoc/guides/rgcms/rgcms.adoc   |   6 +-
 .../guides/rgfis/_rgfis_application-layer.adoc  |  16 +--
 .../guides/rgfis/_rgfis_persistence-layer.adoc  |  22 ++--
 .../guides/rgfis/_rgfis_presentation-layer.adoc |   8 +-
 .../_rgfis_spi_AuditingServiceInternal.adoc     |  20 ++--
 ...rgfis_spi_AuthenticationSessionProvider.adoc |   2 +-
 ...rgfis_spi_ChangedObjectsServiceInternal.adoc |  16 +--
 .../_rgfis_spi_CommandDtoServiceInternal.adoc   |  16 +--
 .../_rgfis_spi_ContentNegotiationService.adoc   |  18 +--
 ...rgfis_spi_InteractionDtoServiceInternal.adoc |   8 +-
 ..._rgfis_spi_MessageBrokerServiceInternal.adoc |   4 +-
 ...s_spi_PersistenceSessionServiceInternal.adoc |   2 +-
 .../_rgfis_spi_PublishingServiceInternal.adoc   |  34 +++---
 .../rgfis/_rgfis_spi_RepresentationService.adoc |  14 +--
 ...is_spi_TransactionStateProviderInternal.adoc |   4 +-
 .../asciidoc/guides/rgmvn/_rgmvn_intro.adoc     |  12 +-
 .../asciidoc/guides/rgmvn/_rgmvn_swagger.adoc   |   4 +-
 .../asciidoc/guides/rgmvn/_rgmvn_validate.adoc  |   6 +-
 .../main/asciidoc/guides/rgmvn/_rgmvn_xsd.adoc  |  10 +-
 .../rgsvc/_rgsvc_api_AcceptHeaderService.adoc   |  18 +--
 .../_rgsvc_api_ActionInvocationContext.adoc     |  12 +-
 ..._rgsvc_api_ApplicationFeatureRepository.adoc |   6 +-
 .../rgsvc/_rgsvc_api_BackgroundService.adoc     |  32 ++---
 .../rgsvc/_rgsvc_api_BookmarkService.adoc       |  16 +--
 .../_rgsvc_api_BulkInteractionContext.adoc      |   2 +-
 .../guides/rgsvc/_rgsvc_api_ClockService.adoc   |   6 +-
 .../guides/rgsvc/_rgsvc_api_CommandContext.adoc |  44 +++----
 .../rgsvc/_rgsvc_api_ConfigurationService.adoc  |  12 +-
 .../rgsvc/_rgsvc_api_DeepLinkService.adoc       |  10 +-
 .../rgsvc/_rgsvc_api_DomainObjectContainer.adoc |   4 +-
 ...nObjectContainer_generic-repository-api.adoc |   4 +-
 ...mainObjectContainer_object-creation-api.adoc |   8 +-
 ...nObjectContainer_object-persistence-api.adoc |   6 +-
 ..._DomainObjectContainer_presentation-api.adoc |   4 +-
 ...pi_DomainObjectContainer_properties-api.adoc |   4 +-
 ..._api_DomainObjectContainer_services-api.adoc |   4 +-
 ...pi_DomainObjectContainer_validation-api.adoc |   2 +-
 .../guides/rgsvc/_rgsvc_api_EmailService.adoc   |   8 +-
 .../rgsvc/_rgsvc_api_EventBusService.adoc       |  40 +++----
 .../guides/rgsvc/_rgsvc_api_FactoryService.adoc |  18 +--
 .../rgsvc/_rgsvc_api_FixtureScriptsDefault.adoc |  12 +-
 .../rgsvc/_rgsvc_api_GuiceBeanProvider.adoc     |   8 +-
 .../_rgsvc_api_HomePageProviderService.adoc     |   6 +-
 .../rgsvc/_rgsvc_api_InteractionContext.adoc    |  42 +++----
 .../guides/rgsvc/_rgsvc_api_IsisJdoSupport.adoc |  16 +--
 .../guides/rgsvc/_rgsvc_api_JaxbService.adoc    |  12 +-
 .../guides/rgsvc/_rgsvc_api_LayoutService.adoc  |  12 +-
 .../guides/rgsvc/_rgsvc_api_MementoService.adoc |  20 ++--
 .../guides/rgsvc/_rgsvc_api_MessageService.adoc |   8 +-
 .../rgsvc/_rgsvc_api_MetamodelService.adoc      |   8 +-
 .../guides/rgsvc/_rgsvc_api_MetricsService.adoc |  10 +-
 .../rgsvc/_rgsvc_api_QueryResultsCache.adoc     |   8 +-
 .../rgsvc/_rgsvc_api_RepositoryService.adoc     |  18 +--
 .../guides/rgsvc/_rgsvc_api_Scratchpad.adoc     |  12 +-
 .../rgsvc/_rgsvc_api_ServiceRegistry.adoc       |  12 +-
 .../_rgsvc_api_SessionManagementService.adoc    |   6 +-
 .../guides/rgsvc/_rgsvc_api_SudoService.adoc    |  18 +--
 .../guides/rgsvc/_rgsvc_api_SwaggerService.adoc |   8 +-
 .../rgsvc/_rgsvc_api_SwitchUserService.adoc     |   2 +-
 .../guides/rgsvc/_rgsvc_api_TitleService.adoc   |   8 +-
 .../rgsvc/_rgsvc_api_TransactionService.adoc    |  12 +-
 .../guides/rgsvc/_rgsvc_api_UserService.adoc    |  10 +-
 .../guides/rgsvc/_rgsvc_api_WrapperFactory.adoc |  16 +--
 .../rgsvc/_rgsvc_api_XmlSnapshotService.adoc    |  14 +--
 .../rgsvc/_rgsvc_application-layer-api.adoc     |  32 ++---
 .../rgsvc/_rgsvc_application-layer-spi.adoc     |   8 +-
 .../guides/rgsvc/_rgsvc_bootstrapping-spi.adoc  |   6 +-
 .../guides/rgsvc/_rgsvc_core-domain-api.adoc    |  28 ++---
 .../guides/rgsvc/_rgsvc_integration-api.adoc    |  16 +--
 .../asciidoc/guides/rgsvc/_rgsvc_intro.adoc     |  78 ++++++------
 .../guides/rgsvc/_rgsvc_metadata-api.adoc       |  14 +--
 .../rgsvc/_rgsvc_persistence-layer-api.adoc     |  10 +-
 .../rgsvc/_rgsvc_persistence-layer-spi.adoc     |  20 ++--
 .../rgsvc/_rgsvc_presentation-layer-spi.adoc    |  44 +++----
 .../guides/rgsvc/_rgsvc_spi_AuditerService.adoc |  16 +--
 .../rgsvc/_rgsvc_spi_AuditingService.adoc       |  10 +-
 .../_rgsvc_spi_BackgroundCommandService.adoc    |  22 ++--
 .../rgsvc/_rgsvc_spi_ClassDiscoveryService.adoc |  14 +--
 .../guides/rgsvc/_rgsvc_spi_CommandService.adoc |  34 +++---
 .../rgsvc/_rgsvc_spi_ContentMappingService.adoc |   8 +-
 .../_rgsvc_spi_EmailNotificationService.adoc    |  14 +--
 .../rgsvc/_rgsvc_spi_ErrorReportingService.adoc |   6 +-
 .../rgsvc/_rgsvc_spi_EventSerializer.adoc       |  14 +--
 .../rgsvc/_rgsvc_spi_ExceptionRecognizer.adoc   |   4 +-
 ...spi_FixtureScriptsSpecificationProvider.adoc |   6 +-
 .../rgsvc/_rgsvc_spi_GridLoaderService.adoc     |  12 +-
 .../guides/rgsvc/_rgsvc_spi_GridService.adoc    |  28 ++---
 .../rgsvc/_rgsvc_spi_GridSystemService.adoc     |  18 +--
 .../guides/rgsvc/_rgsvc_spi_HintStore.adoc      |  10 +-
 .../guides/rgsvc/_rgsvc_spi_LocaleProvider.adoc |  12 +-
 .../rgsvc/_rgsvc_spi_PublisherService.adoc      |  40 +++----
 .../rgsvc/_rgsvc_spi_PublishingService.adoc     |  36 +++---
 .../guides/rgsvc/_rgsvc_spi_RoutingService.adoc |  14 +--
 .../_rgsvc_spi_TableColumnOrderService.adoc     |   4 +-
 .../rgsvc/_rgsvc_spi_TranslationService.adoc    |   8 +-
 .../rgsvc/_rgsvc_spi_TranslationsResolver.adoc  |  10 +-
 .../rgsvc/_rgsvc_spi_UrlEncodingService.adoc    |   6 +-
 .../_rgsvc_spi_UserRegistrationService.adoc     |   8 +-
 .../asciidoc/guides/rgsvc/_rgsvc_testing.adoc   |  18 +--
 .../ugbtb/_ugbtb_decoupling_contributions.adoc  |   2 +-
 .../ugbtb/_ugbtb_decoupling_event-bus.adoc      |   2 +-
 .../guides/ugbtb/_ugbtb_decoupling_mixins.adoc  |  10 +-
 .../_ugbtb_decoupling_pushing-changes.adoc      |   4 +-
 .../_ugbtb_decoupling_vetoing-visibility.adoc   |   2 +-
 .../ugbtb/_ugbtb_deployment_cmd-line.adoc       |   4 +-
 .../guides/ugbtb/_ugbtb_deployment_docker.adoc  |   2 +-
 ...b_deployment_externalized-configuration.adoc |   2 +-
 .../guides/ugbtb/_ugbtb_deployment_neo4j.adoc   |   6 +-
 .../guides/ugbtb/_ugbtb_deployment_tomcat.adoc  |   2 +-
 .../guides/ugbtb/_ugbtb_headless-access.adoc    |   2 +-
 ...dless-access_BackgroundCommandExecution.adoc |   6 +-
 .../main/asciidoc/guides/ugbtb/_ugbtb_i18n.adoc |  16 +--
 ..._ugbtb_other-techniques_persisted-title.adoc |   2 +-
 ...placing-default-service-implementations.adoc |   6 +-
 ...ther-techniques_transactions-and-errors.adoc |   8 +-
 ...gbtb_programming-model_custom-validator.adoc |   4 +-
 .../guides/ugbtb/_ugbtb_view-models_jaxb.adoc   |  20 ++--
 .../_ugbtb_view-models_programming-model.adoc   |  10 +-
 .../ugbtb/_ugbtb_view-models_use-cases.adoc     |  14 +--
 .../asciidoc/guides/ugbtb/_ugbtb_web-xml.adoc   |   2 +-
 ...ugfun_core-concepts_apache-isis-vs_cqrs.adoc |   6 +-
 ...-concepts_apache-isis-vs_event-sourcing.adoc |   4 +-
 ...core-concepts_apache-isis-vs_metawidget.adoc |   2 +-
 .../_ugfun_core-concepts_building-blocks.adoc   |  20 ++--
 ...re-concepts_framework-provided-services.adoc | 120 +++++++++----------
 ..._core-concepts_other-deployment-options.adoc |   4 +-
 .../_ugfun_core-concepts_philosophy_aop.adoc    |   4 +-
 ..._core-concepts_philosophy_how-eases-ddd.adoc |   2 +-
 ...bjects-pattern_object-interface-mapping.adoc |   2 +-
 ...e-concepts_principles_for-the-long-term.adoc |   4 +-
 .../guides/ugfun/_ugfun_getting-started.adoc    |   8 +-
 ...un_getting-started_datanucleus-enhancer.adoc |   8 +-
 ...fun_getting-started_simpleapp-archetype.adoc |   6 +-
 .../ugfun/_ugfun_how-tos_bulk-actions.adoc      |   2 +-
 .../ugfun/_ugfun_how-tos_business-rules.adoc    |   8 +-
 .../_ugfun_how-tos_class-structure_actions.adoc |  36 +++---
 ...ow-tos_class-structure_class-definition.adoc |   4 +-
 ...fun_how-tos_class-structure_collections.adoc |   8 +-
 ...how-tos_class-structure_inject-services.adoc |   4 +-
 ...gfun_how-tos_class-structure_properties.adoc |  10 +-
 .../guides/ugfun/_ugfun_how-tos_crud.adoc       |   8 +-
 .../ugfun/_ugfun_how-tos_derived-members.adoc   |   4 +-
 .../ugfun/_ugfun_how-tos_domain-services.adoc   |  24 ++--
 .../_ugfun_how-tos_drop-downs-and-defaults.adoc |  18 +--
 ...ow-tos_simulating-collections-of-values.adoc |   2 +-
 ...n_how-tos_ui-hints_action-icons-and-css.adoc |  10 +-
 ...how-tos_ui-hints_names-and-descriptions.adoc |  10 +-
 ...ow-tos_ui-hints_object-titles-and-icons.adoc |  10 +-
 .../ugfun/_ugfun_how-tos_ui_are-you-sure.adoc   |   4 +-
 .../src/main/asciidoc/guides/ugfun/ugfun.adoc   |   8 +-
 ...g_disabling-persistence-by-reachability.adoc |   4 +-
 ...onfiguring_eagerly-registering-entities.adoc |   2 +-
 .../ugodn/_ugodn_configuring_properties.adoc    |   2 +-
 .../_ugodn_overriding-jdo-annotations.adoc      |   2 +-
 .../ugsec/_ugsec_api-for-applications.adoc      |   2 +-
 .../_ugsec_configuring-isis-to-use-shiro.adoc   |   2 +-
 .../guides/ugsec/_ugsec_shiro-ini-realm.adoc    |   2 +-
 .../ugsec/_ugsec_usage-by-isis-viewers.adoc     |   4 +-
 .../src/main/asciidoc/guides/ugsec/ugsec.adoc   |  10 +-
 ...st_bdd-spec-support_maven-configuration.adoc |   2 +-
 ...tst_bdd-spec-support_writing-a-bdd-spec.adoc |   6 +-
 .../_ugtst_fixture-scripts_api-and-usage.adoc   |  18 +--
 ..._ugtst_integ-test-support_bootstrapping.adoc |  12 +-
 ..._integ-test-support_maven-configuration.adoc |   2 +-
 ..._ugtst_integ-test-support_typical-usage.adoc |   2 +-
 ...gtst_integ-test-support_wrapper-factory.adoc |   4 +-
 .../asciidoc/guides/ugtst/_ugtst_overview.adoc  |   4 +-
 ..._ugtst_unit-test-support_contract-tests.adoc |   6 +-
 ...t_unit-test-support_maven-configuration.adoc |   2 +-
 .../guides/ugvro/_ugvro_architecture.adoc       |   6 +-
 .../guides/ugvro/_ugvro_hints-and-tips.adoc     |   2 +-
 .../asciidoc/guides/ugvro/_ugvro_ro-spec.adoc   |   2 +-
 .../ugvw/_ugvw_configuration-properties.adoc    |   2 +-
 .../ugvw/_ugvw_customisation_about-page.adoc    |   2 +-
 .../ugvw/_ugvw_customisation_brand-logo.adoc    |   2 +-
 ...ugvw_customisation_tweaking-css-classes.adoc |   4 +-
 .../ugvw/_ugvw_extending_custom-pages.adoc      |   4 +-
 .../ugvw/_ugvw_features_blob-attachments.adoc   |   2 +-
 .../ugvw/_ugvw_features_bookmarked-pages.adoc   |   6 +-
 .../ugvw/_ugvw_features_user-registration.adoc  |  10 +-
 .../ugvw/_ugvw_layout_annotation-based.adoc     |  18 +--
 .../guides/ugvw/_ugvw_layout_file-based.adoc    |  30 ++---
 .../guides/ugvw/_ugvw_layout_table-columns.adoc |   2 +-
 419 files changed, 2000 insertions(+), 2000 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_asciidoc-publish-procedure.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_asciidoc-publish-procedure.adoc b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_asciidoc-publish-procedure.adoc
index 53a0c33..f0c9b34 100644
--- a/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_asciidoc-publish-procedure.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_asciidoc-publish-procedure.adoc
@@ -11,8 +11,8 @@ Apache Isis' documentation (meaning the website and the users' guide, the refere
 The website and guides are created by running build tools (documented below) which create the HTML version of the site and guides.
 You can therefore easily check the documentation before raising a pull request (as a contributor) or publishing the site (if a committer).
 
-For details of authoring/updating the documents and website, see the xref:dg.adoc#_dg_asciidoc[developers' guide].
-To help write the Asciidoc text itself, we provide some xref:dg.adoc#_dg_asciidoc-templates[Asciidoc templates].
+For details of authoring/updating the documents and website, see the xref:../dg/dg.adoc#_dg_asciidoc[developers' guide].
+To help write the Asciidoc text itself, we provide some xref:../dg/dg.adoc#_dg_asciidoc-templates[Asciidoc templates].
 
 Publishing is performed by copying the generated HTML to a different git repository (link:https://git-wip-us.apache.org/repos/asf?p=isis-site.git[isis-site]).
 This is synced by ASF infrastructure over to link:http://isis.apache.org[isis.apache.org].

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_cutting-a-release.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_cutting-a-release.adoc b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_cutting-a-release.adoc
index 31fda99..2bae3a9 100644
--- a/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_cutting-a-release.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_cutting-a-release.adoc
@@ -9,17 +9,17 @@
 The release process consists of:
 
 * the release manager cutting the release (documented below)
-* Members of the Apache Isis PMC xref:cgcom.adoc#_cgcom_verifying-releases[verifying] and voting on the release
-* the release manager performing post-release tasks, for either a xref:cgcom.adoc#_cgcom_post-release-successful[successful] or an xref:cgcom.adoc#_cgcom_post-release-unsuccessful[unsuccessful] vote.
+* Members of the Apache Isis PMC xref:../cgcom/cgcom.adoc#_cgcom_verifying-releases[verifying] and voting on the release
+* the release manager performing post-release tasks, for either a xref:../cgcom/cgcom.adoc#_cgcom_post-release-successful[successful] or an xref:../cgcom/cgcom.adoc#_cgcom_post-release-unsuccessful[unsuccessful] vote.
 
 Apache Isis itself consists of two separately releasable modules; relative to the link:https://git-wip-us.apache.org/repos/asf/isis/repo?p=isis.git;a=tree[source code root] there are:
 
 * `core`
 * `component/example/archetypes/simpleapp`
 
-This section details the process for formally releasing Isis modules.  It describes the process for both `core` and then the archetype.  The subsequent sections describe how other committers can xref:cgcom.adoc#_cgcom_verifying-releases[verify a release] and how the release manager can then perform xref:cgcom.adoc#_cgcom_post-release[post-release] activities and set up for the next development iteration.
+This section details the process for formally releasing Isis modules.  It describes the process for both `core` and then the archetype.  The subsequent sections describe how other committers can xref:../cgcom/cgcom.adoc#_cgcom_verifying-releases[verify a release] and how the release manager can then perform xref:../cgcom/cgcom.adoc#_cgcom_post-release[post-release] activities and set up for the next development iteration.
 
-If you've not performed a release before, then note that there are some configuration xref:cgcom.adoc#_cgcom_release-process-prereqs[prerequisites] that must be configured first.  In particular, you'll need signed public/private keys, and the ASF Nexus staging repo inlocal `~/.m2/settings.xml` file.
+If you've not performed a release before, then note that there are some configuration xref:../cgcom/cgcom.adoc#_cgcom_release-process-prereqs[prerequisites] that must be configured first.  In particular, you'll need signed public/private keys, and the ASF Nexus staging repo inlocal `~/.m2/settings.xml` file.
 
 These release notes using bash command line tools.  They should work on Linux and MacOS; for Windows, use mSysGit.
 
@@ -31,7 +31,7 @@ These release notes using bash command line tools.  They should work on Linux an
 
 Before releasing `core`, ensure there is consensus on the link:../support.html[dev mailing list] that this is the right time for a release. The discussion should include confirming the version number to be used, and to confirm content.
 
-These discussions should also confirm the version number of the module being released. This should be in line with our xref:cgcom.adoc#_cgcom_versioning-policy[semantic versioning policy].
+These discussions should also confirm the version number of the module being released. This should be in line with our xref:../cgcom/cgcom.adoc#_cgcom_versioning-policy[semantic versioning policy].
 
 
 Make sure you have a JIRA ticket open against which to perform all commits.  In most cases a JIRA ticket will have been created at the beginning of the previous release cycle.
@@ -57,10 +57,10 @@ export CATALINA_HOME=/c/java/apache-tomcat-8.0.30   # <3>
 env | grep ISIS | sort
 ----
 <1> adjust by platform
-<2> set to an "umbrella" ticket for all release activities.  (One should exist already, xref:cgcom.adoc#__cgcom_post-release-successful_update-jira_create-new-jira[created at] the beginning of the development cycle now completing).
+<2> set to an "umbrella" ticket for all release activities.  (One should exist already, xref:../cgcom/cgcom.adoc#__cgcom_post-release-successful_update-jira_create-new-jira[created at] the beginning of the development cycle now completing).
 <3> adjust as required (Tomcat is used to smoke test the simpleapp archetype)
 
-Obviously, alter `$ISISDEV` and `$ISISREL` as required, and bump `$ISISRC` for re-releasing following an xref:cgcom.adoc#_cgcom_post-release-unsuccessful[unsuccessful] releases.
+Obviously, alter `$ISISDEV` and `$ISISREL` as required, and bump `$ISISRC` for re-releasing following an xref:../cgcom/cgcom.adoc#_cgcom_post-release-unsuccessful[unsuccessful] releases.
 
 [IMPORTANT]
 ====
@@ -633,7 +633,7 @@ Use `gpg --keyserver hkp://pgp.mit.edu --recv-keys nnnnnnnn` to confirm that the
 
 [NOTE]
 ====
-Unfortunately, Nexus does not seem to allow subkeys to be used for signing. See xref:cgcom.adoc#_cgcom_key-generation[Key Generation] for more details.
+Unfortunately, Nexus does not seem to allow subkeys to be used for signing. See xref:../cgcom/cgcom.adoc#_cgcom_key-generation[Key Generation] for more details.
 ====
 
 
@@ -716,7 +716,7 @@ Remember to update:
 * the release candidate number (`RC1` or whatever)
 * the repository id, as provided by Nexus earlier (`orgapacheisis-10xx` or whatever)
 
-Note that the email also references the procedure for other committers to xref:cgcom.adoc#_cgcom_verifying-releases[verify the release].
+Note that the email also references the procedure for other committers to xref:../cgcom/cgcom.adoc#_cgcom_verifying-releases[verify the release].
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_policies_git-policy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_policies_git-policy.adoc b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_policies_git-policy.adoc
index a116e83..f45591e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_policies_git-policy.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_policies_git-policy.adoc
@@ -95,4 +95,4 @@ ISIS-nnn: brief summary here
 
 where `ISIS-nnn` is a ticket raised in our https://issues.apache.org/jira/browse/ISIS[JIRA issue tracker].
 
-For non-committers we typically expect more detail again; see the xref:dg.adoc#_dg_contributing[contributing] page for the longer format recommended for contributors to use.
\ No newline at end of file
+For non-committers we typically expect more detail again; see the xref:../dg/dg.adoc#_dg_contributing[contributing] page for the longer format recommended for contributors to use.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_post-release-successful.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_post-release-successful.adoc b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_post-release-successful.adoc
index d113a6b..0bb3870 100644
--- a/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_post-release-successful.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_post-release-successful.adoc
@@ -8,9 +8,9 @@
 
 The release process consists of:
 
-* the release manager xref:cgcom.adoc#_cgcom_cutting-a-release[cutting the release]
-* members of the Apache Isis PMC xref:cgcom.adoc#_cgcom_verifying-releases[verifying] and voting on the release
-* the release manager performing post-release tasks, for either a successful or an xref:cgcom.adoc#_cgcom_post-release-unsuccessful[unsuccessful] vote (former documented below)
+* the release manager xref:../cgcom/cgcom.adoc#_cgcom_cutting-a-release[cutting the release]
+* members of the Apache Isis PMC xref:../cgcom/cgcom.adoc#_cgcom_verifying-releases[verifying] and voting on the release
+* the release manager performing post-release tasks, for either a successful or an xref:../cgcom/cgcom.adoc#_cgcom_post-release-unsuccessful[unsuccessful] vote (former documented below)
 
 For a vote to succeed, there must be +3 votes from PMC members, and the vote must have been open at least 72 hours.  If there are not +3 votes after this time then it is perfectly permissible to keep the vote open longer.
 
@@ -545,7 +545,7 @@ to review changes made.
 foreach -g isisaddons/isis-[mw] sh release.sh "1.14.0" "1.15.0-SNAPSHOT" "dan@haywood-associates.co.uk" \"this is not really my password\"
 ----
 
-* In the parent directory where the `last_modified.sh` script has been saved (see xref:cgcom.adoc#__cgcom_post-release-successful_release-non-asf-modules_prereqs[above]), use to check that all modules were released successfully: +
+* In the parent directory where the `last_modified.sh` script has been saved (see xref:../cgcom/cgcom.adoc#__cgcom_post-release-successful_release-non-asf-modules_prereqs[above]), use to check that all modules were released successfully: +
 +
 [source,bash]
 ----
@@ -608,7 +608,7 @@ eg if using Windows, then: +
 +
 [TIP]
 ====
-See xref:cgcom.adoc#__cgcom_post-release-successful_release-non-asf-modules_incode-catalog_cross-module-dependencies[below] for a list of the dependencies to update.
+See xref:../cgcom/cgcom.adoc#__cgcom_post-release-successful_release-non-asf-modules_incode-catalog_cross-module-dependencies[below] for a list of the dependencies to update.
 ====
 
 * If necessary, adjust the `_repos.txt` file (used by `foreach` function) so that repositories are released in the correct sequence (with respect to their mutual dependencies).
@@ -621,7 +621,7 @@ For example, `incode-module-base` must be released prior to `incode-module-alias
 foreach -g incodehq/incode-module-[a-w] sh release.sh "1.14.0" "1.15.0-SNAPSHOT" "dan@haywood-associates.co.uk" \"this is not really my password\"
 ----
 
-* In the parent directory where the `last_modified.sh` script has been saved (see xref:cgcom.adoc#__cgcom_post-release-successful_release-non-asf-modules_prereqs[above]), use to check that all modules were released successfully: +
+* In the parent directory where the `last_modified.sh` script has been saved (see xref:../cgcom/cgcom.adoc#__cgcom_post-release-successful_release-non-asf-modules_prereqs[above]), use to check that all modules were released successfully: +
 +
 [source,bash]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_post-release-unsuccessful.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_post-release-unsuccessful.adoc b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_post-release-unsuccessful.adoc
index bf9e40e..94b80f5 100644
--- a/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_post-release-unsuccessful.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_post-release-unsuccessful.adoc
@@ -8,9 +8,9 @@
 
 The release process consists of:
 
-* the release manager xref:cgcom.adoc#_cgcom_cutting-a-release[cutting the release]
-* members of the Apache Isis PMC xref:cgcom.adoc#_cgcom_verifying-releases[verifying] and voting on the release
-* the release manager performing post-release tasks, for either a xref:cgcom.adoc#_cgcom_post-release-successful[successful] or an unsuccessful vote (latter documented below).
+* the release manager xref:../cgcom/cgcom.adoc#_cgcom_cutting-a-release[cutting the release]
+* members of the Apache Isis PMC xref:../cgcom/cgcom.adoc#_cgcom_verifying-releases[verifying] and voting on the release
+* the release manager performing post-release tasks, for either a xref:../cgcom/cgcom.adoc#_cgcom_post-release-successful[successful] or an unsuccessful vote (latter documented below).
 
 If the vote did not succeed (did not achieve +3 votes after 72 hours and/or is unlikely to do so), then the vote should be closed and the following steps performed.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_release-process-for-interim-releases.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_release-process-for-interim-releases.adoc b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_release-process-for-interim-releases.adoc
index e021a10..4966537 100644
--- a/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_release-process-for-interim-releases.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_release-process-for-interim-releases.adoc
@@ -8,7 +8,7 @@
 
 The intent of an "interim" release is to allow a developer team to release their application based on a `-SNAPSHOT` version of the framework.  Since `-SNAPSHOT` changes on a day-to-day basis, the idea is to tag a particular revision and to release this, thereby providing stability/traceability for the application being developed.
 
-Whereas xref:cgcom.adoc#_cgcom_cutting-a-release.adoc[formal release]s and xref:cgcom.adoc#_cgcom_relesae-process-for-snapshots.adoc[snapshot release]s are public (released through the Maven repository maintained by Apache Software Foundation), interim releases are non-public and rely on infrastructure provided by a developer team.  The tagged release resides _not_ in the link:../downloads.adoc#_downloads_source_code[official Apache Isis git repository], but instead in a fork/clone maintained by the developer team.
+Whereas xref:../cgcom/cgcom.adoc#_cgcom_cutting-a-release.adoc[formal release]s and xref:../cgcom/cgcom.adoc#_cgcom_relesae-process-for-snapshots.adoc[snapshot release]s are public (released through the Maven repository maintained by Apache Software Foundation), interim releases are non-public and rely on infrastructure provided by a developer team.  The tagged release resides _not_ in the link:../downloads.adoc#_downloads_source_code[official Apache Isis git repository], but instead in a fork/clone maintained by the developer team.
 
 [NOTE]
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_release-process-prereqs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_release-process-prereqs.adoc b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_release-process-prereqs.adoc
index ac758da..d2c9491 100644
--- a/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_release-process-prereqs.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_release-process-prereqs.adoc
@@ -7,7 +7,7 @@
 
 
 
-This section (appendix) describes the prerequisites for the xref:cgcom.adoc#_cgcom_release-process[release process].
+This section (appendix) describes the prerequisites for the xref:../cgcom/cgcom.adoc#_cgcom_release-process[release process].
 
 
 
@@ -22,7 +22,7 @@ Ensure that Java 7 is installed and the toolchains plugin is configured, as desc
 
 The most important configuration you require is to set up public/private key pair.
 This is used by the `maven-release-plugin` to sign the code artifacts.
-See the page on xref:cgcom.adoc#_cgcom_key-generation[key generation] for more details.
+See the page on xref:../cgcom/cgcom.adoc#_cgcom_key-generation[key generation] for more details.
 
 In order to prepare the release, you'll (need to) have a `~/.gnupg` directory with the relevant files (`gpg.conf`, `pubring.gpg`, `secring.gpg` etc), and have `gpg` on your operating system PATH.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_verifying-releases.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_verifying-releases.adoc b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_verifying-releases.adoc
index ea9588b..e56d74e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_verifying-releases.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_verifying-releases.adoc
@@ -8,9 +8,9 @@
 
 The release process consists of:
 
-* the release manager xref:cgcom.adoc#_cgcom_cutting-a-release[cutting the release]
+* the release manager xref:../cgcom/cgcom.adoc#_cgcom_cutting-a-release[cutting the release]
 * members of the Apache Isis PMC verifying and voting on the release (documented below)
-* the release manager performing post-release tasks, for either a xref:cgcom.adoc#_cgcom_post-release-successful[successful] or an xref:cgcom.adoc#_cgcom_post-release-unsuccessful[unsuccessful] vote.
+* the release manager performing post-release tasks, for either a xref:../cgcom/cgcom.adoc#_cgcom_post-release-successful[successful] or an xref:../cgcom/cgcom.adoc#_cgcom_post-release-unsuccessful[unsuccessful] vote.
 
 This section describes some guidance on what a voter (members of the Apache Isis PMC and anyone else who wishes) is expected to do before casting their vote in order to verify a release.
 
@@ -18,7 +18,7 @@ This section describes some guidance on what a voter (members of the Apache Isis
 
 == Background
 
-Whenever a release manager announces a vote on a release (as per the xref:cgcom.adoc#_cgcom_release-process[release process]) on the link:../support.html[dev mailing list], it is the responsibility of the project's PMC to cast their vote on the release.  Anyone else can also vote, but only members of the Apache Isis PMC's vote are binding.
+Whenever a release manager announces a vote on a release (as per the xref:../cgcom/cgcom.adoc#_cgcom_release-process[release process]) on the link:../support.html[dev mailing list], it is the responsibility of the project's PMC to cast their vote on the release.  Anyone else can also vote, but only members of the Apache Isis PMC's vote are binding.
 
 Per this http://www.apache.org/dev/release.html[ASF documentation], the legal requirements for an ASF release are:
 
@@ -53,7 +53,7 @@ rm -rf ~/.m2/repository/org/apache/isis
 
 == Verifying source artifacts
 
-You can either verify the source artifacts xref:cgcom.adoc#__cgcom_verifying-releases_manual-procedure[manuall], or use a script that xref:cgcom.adoc#__cgcom_verifying-releases_automated-procedure[automates] the steps.
+You can either verify the source artifacts xref:../cgcom/cgcom.adoc#__cgcom_verifying-releases_manual-procedure[manuall], or use a script that xref:../cgcom/cgcom.adoc#__cgcom_verifying-releases_automated-procedure[automates] the steps.
 
 
 [[__cgcom_verifying-releases_manual-procedure]]
@@ -95,7 +95,7 @@ Confirm that the versions of the Isis artifacts now cached in your local reposit
 
 ==== Verifying binary artifacts
 
-You can verify the binary releases by configuring your local Maven install to point to the Maven staging repository (or repositories) and then using them, eg to run the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype1] and running the resultant app.
+You can verify the binary releases by configuring your local Maven install to point to the Maven staging repository (or repositories) and then using them, eg to run the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype1] and running the resultant app.
 
 Configuring your local Maven install amounts to updating the `~/.m2/settings.xml` file:
 
@@ -254,7 +254,7 @@ Execute...
 
 The http://creadur.apache.org[Apache Creadur] project exists to provide a set of tools to ensure compliance with Apache's licensing standards.
 
-The main release auditing tool, http://creadur.apache.org/rat[Apache RAT] is used in the xref:cgcom.adoc#_cgcom_cutting-a-release[release process].
+The main release auditing tool, http://creadur.apache.org/rat[Apache RAT] is used in the xref:../cgcom/cgcom.adoc#_cgcom_cutting-a-release[release process].
 
 Creadur's remaining tools - link:http://creadur.apache.org/tentacles/[Tentacles] and link:http://creadur.apache.org/whisker/[Whisker] - are to support the verification process.
 
@@ -293,7 +293,7 @@ cd webapp
 mvn jetty:run
 ----
 
-Adjust the version as necessary.  If it runs up ok, then it's time to xref:cgcom.adoc#_cgcom_verifying-releases[vote]!
+Adjust the version as necessary.  If it runs up ok, then it's time to xref:../cgcom/cgcom.adoc#_cgcom_verifying-releases[vote]!
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc-templates.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc-templates.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc-templates.adoc
index 82fd819..8c8fc58 100644
--- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc-templates.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc-templates.adoc
@@ -7,7 +7,7 @@
 
 
 
-This appendix lists the (IntelliJ) live templates available for xref:dg.adoc#_dg_asciidoc[writing documentation] using Asciidoc.  Instructions for installing the templates can be found xref:dg.adoc#__dg_ide_intellij_live-templates[here].
+This appendix lists the (IntelliJ) live templates available for xref:../dg/dg.adoc#_dg_asciidoc[writing documentation] using Asciidoc.  Instructions for installing the templates can be found xref:../dg/dg.adoc#__dg_ide_intellij_live-templates[here].
 
 In the examples below the text `xxx`, `yyy`, `zzz` are correspond to template variables (ie placeholders).
 
@@ -122,7 +122,7 @@ Cross-references (links) to the various guides
 
 
 |`adcgcom`
-|`\xref:cgcom.adoc#xxx[ttt]`
+|`\xref:../cgcom/cgcom.adoc#xxx[ttt]`
 
 a hyperlink to a bookmark within the committers' guide, where:
 
@@ -131,10 +131,10 @@ a hyperlink to a bookmark within the committers' guide, where:
 
 for example:
 
-`\xref:dg.adoc#_cgcom_cutting-a-release[Cutting a release\]`
+`\xref:../dg/dg.adoc#_cgcom_cutting-a-release[Cutting a release\]`
 
 |`addg`
-|`\xref:dg.adoc#xxx[ttt]`
+|`\xref:../dg/dg.adoc#xxx[ttt]`
 
 a hyperlink to a bookmark within the developers' guide, where:
 
@@ -143,14 +143,14 @@ a hyperlink to a bookmark within the developers' guide, where:
 
 for example:
 
-`\xref:dg.adoc#_dg_asciidoc-templates[Asciidoc templates\]`
+`\xref:../dg/dg.adoc#_dg_asciidoc-templates[Asciidoc templates\]`
 
-|xref:dg.adoc#_dg_asciidoc-templates[Asciidoc templates]
+|xref:../dg/dg.adoc#_dg_asciidoc-templates[Asciidoc templates]
 
 
 
 |`adrgant`
-|`\xref:rgant.adoc#xxx[ttt]`
+|`\xref:../rgant/rgant.adoc#xxx[ttt]`
 
 a hyperlink to a bookmark within the reference guide for annotations, where:
 
@@ -159,14 +159,14 @@ a hyperlink to a bookmark within the reference guide for annotations, where:
 
 for example:
 
-`\xref:rgant.adoc#_rgant-aaa_main[Core annotations]`
+`\xref:../rgant/rgant.adoc#_rgant-aaa_main[Core annotations]`
 
-|xref:rgant.adoc#_rgant-aaa_main[Core annotations]
+|xref:../rgant/rgant.adoc#_rgant-aaa_main[Core annotations]
 
 
 
 |`adrgcfg`
-|`\xref:rgcfg.adoc#xxx[ttt]`
+|`\xref:../rgcfg/rgcfg.adoc#xxx[ttt]`
 
 a hyperlink to a bookmark within the reference guide for configuration properties guide, where:
 
@@ -175,14 +175,14 @@ a hyperlink to a bookmark within the reference guide for configuration propertie
 
 for example:
 
-`\xref:rgcfg.adoc#_rgcfg_configuring-core[Configuring Core]`
+`\xref:../rgcfg/rgcfg.adoc#_rgcfg_configuring-core[Configuring Core]`
 
-|xref:rgcfg.adoc#_rgcfg_configuring-core[Configuring Core]
+|xref:../rgcfg/rgcfg.adoc#_rgcfg_configuring-core[Configuring Core]
 
 
 
 |`adrgcms`
-|`\xref:rgcms.adoc#xxx[ttt]`
+|`\xref:../rgcms/rgcms.adoc#xxx[ttt]`
 
 a hyperlink to a bookmark within the reference guide for classes, methods and schema, where:
 
@@ -191,14 +191,14 @@ a hyperlink to a bookmark within the reference guide for classes, methods and sc
 
 for example:
 
-`\xref:rgcms.adoc#_rgcms_classes_super_AbstractService[`AbstractService`]`
+`\xref:../rgcms/rgcms.adoc#_rgcms_classes_super_AbstractService[`AbstractService`]`
 
-|xref:rgcms.adoc#_rgcms_classes_super_AbstractService[`AbstractService`]
+|xref:../rgcms/rgcms.adoc#_rgcms_classes_super_AbstractService[`AbstractService`]
 
 
 
 |`adrgsvc`
-|`\xref:rgsvc.adoc#xxx[ttt]`
+|`\xref:../rgsvc/rgsvc.adoc#xxx[ttt]`
 
 a hyperlink to a bookmark within the reference guide for domain services, where:
 
@@ -207,14 +207,14 @@ a hyperlink to a bookmark within the reference guide for domain services, where:
 
 for example:
 
-`\xref:rgsvc.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest` bootstrapping]`
+`\xref:../rgsvc/rgsvc.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest` bootstrapping]`
 
-|xref:rgsvc.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest` bootstrapping]
+|xref:../rgsvc/rgsvc.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest` bootstrapping]
 
 
 
 |`adrgmvn`
-|`\xref:rgmvn.adoc#xxx[ttt]`
+|`\xref:../rgmvn/rgmvn.adoc#xxx[ttt]`
 
 a hyperlink to a bookmark within the reference guide for the maven plugin, where:
 
@@ -223,14 +223,14 @@ a hyperlink to a bookmark within the reference guide for the maven plugin, where
 
 for example:
 
-`\xref:rgmvn.adoc#_rgmvn_validate[validate goal]`
+`\xref:../rgmvn/rgmvn.adoc#_rgmvn_validate[validate goal]`
 
-|xref:rgmvn.adoc#_rgmvn_validate[validate goal]
+|xref:../rgmvn/rgmvn.adoc#_rgmvn_validate[validate goal]
 
 
 
 |`adrgna`
-|`\xref:rgant.adoc#_rgant-xxx[`@xxx`]`
+|`\xref:../rgant/rgant.adoc#_rgant-xxx[`@xxx`]`
 
 a hyperlink to the "man page" for an annotation within the reference guide for annotations, where:
 
@@ -238,14 +238,14 @@ a hyperlink to the "man page" for an annotation within the reference guide for a
 
 for example:
 
-`\xref:rgant.adoc#_rgant-Action[`@Action`]`
+`\xref:../rgant/rgant.adoc#_rgant-Action[`@Action`]`
 
-|xref:rgant.adoc#_rgant-Action[`@Action`]
+|xref:../rgant/rgant.adoc#_rgant-Action[`@Action`]
 
 
 
 |`adrgnt`
-|`\xref:rgant.adoc#_rgant-xxx_ttt[`@xxx#ttt()`]`
+|`\xref:../rgant/rgant.adoc#_rgant-xxx_ttt[`@xxx#ttt()`]`
 
 a hyperlink to the "man page" for the specific attribute (field) of an annotation within the reference guide for annotations, where:
 
@@ -254,14 +254,14 @@ a hyperlink to the "man page" for the specific attribute (field) of an annotatio
 
 for example:
 
-`\xref:rgant.adoc#_rgant-Action_semantics[`@Action#semantics()`]`
+`\xref:../rgant/rgant.adoc#_rgant-Action_semantics[`@Action#semantics()`]`
 
-|xref:rgant.adoc#_rgant-Action_semantics[`@Action#semantics()`]
+|xref:../rgant/rgant.adoc#_rgant-Action_semantics[`@Action#semantics()`]
 
 
 
 |`adrgsa`
-|`\xref:rgsvc.adoc#_rgsvc_api_xxx[`xxx`]`
+|`\xref:../rgsvc/rgsvc.adoc#_rgsvc_api_xxx[`xxx`]`
 
 a hyperlink to the "man page" for an (API) domain service within the reference guide for domain services, where:
 
@@ -269,14 +269,14 @@ a hyperlink to the "man page" for an (API) domain service within the reference g
 
 for example:
 
-`\xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`]`
+`\xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`]`
 
-|xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`]
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`]
 
 
 
 |`adrgss`
-|`\xref:rgsvc.adoc#_rgsvc_spi_xxx[`xxx`]`
+|`\xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_xxx[`xxx`]`
 
 a hyperlink to the "man page" for an (SPI) domain service within the reference guide for domain services, where:
 
@@ -284,15 +284,15 @@ a hyperlink to the "man page" for an (SPI) domain service within the reference g
 
 for example:
 
-`\xref:rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`]`
+`\xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`]`
 
-|xref:rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`]
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`]
 
 
 
 
 |`adugfun`
-|`\xref:ugfun.adoc#xxx[ttt]`
+|`\xref:../ugfun/ugfun.adoc#xxx[ttt]`
 
 a hyperlink to a bookmark within the fundamentals users' guide, where:
 
@@ -301,9 +301,9 @@ a hyperlink to a bookmark within the fundamentals users' guide, where:
 
 for example:
 
-`\xref:ugfun.adoc#_ugfun_core-concepts[Core concepts]`
+`\xref:../ugfun/ugfun.adoc#_ugfun_core-concepts[Core concepts]`
 
-|xref:ugfun.adoc#_ugfun_core-concepts[Core concepts]
+|xref:../ugfun/ugfun.adoc#_ugfun_core-concepts[Core concepts]
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc.adoc
index cc55355..02d3d79 100644
--- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc.adoc
@@ -13,10 +13,10 @@ Apache Isis' documentation (meaning the website and the users' guide, the refere
 The website and guides are created by running build tools (documented below) which create the HTML version of the site and guides.
 You can therefore easily check the documentation before raising a pull request (as a contributor) or publishing the site (if a committer).
 
-To help write the Asciidoc text itself, we provide some xref:dg.adoc#_dg_asciidoc-templates[Asciidoc templates].
+To help write the Asciidoc text itself, we provide some xref:../dg/dg.adoc#_dg_asciidoc-templates[Asciidoc templates].
 
 Publishing is performed by copying the generated HTML to a different git repository (link:https://git-wip-us.apache.org/repos/asf?p=isis-site.git[isis-site]).
-Since this can only be done by Apache Isis committers, the process for doing this is described in the xref:cgcom.adoc#_cgcom_asciidoc-publish-procedure[committers' guide].
+Since this can only be done by Apache Isis committers, the process for doing this is described in the xref:../cgcom/cgcom.adoc#_cgcom_asciidoc-publish-procedure[committers' guide].
 This is synced by ASF infrastructure over to link:http://isis.apache.org[isis.apache.org].
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc_publish-procedure.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc_publish-procedure.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc_publish-procedure.adoc
index f7dcc2e..b3ae7ab 100644
--- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc_publish-procedure.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc_publish-procedure.adoc
@@ -9,5 +9,5 @@
 
 
 Only Apache Isis committers can publish to link:http://isis.apache.org[isis.apache.org].
-See the xref:cgcom.adoc#_cgcom_publishing-the-docs[committers' guide] for further details.
+See the xref:../cgcom/cgcom.adoc#_cgcom_publishing-the-docs[committers' guide] for further details.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc_writing-the-docs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc_writing-the-docs.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc_writing-the-docs.adoc
index 51da1b0..311144c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc_writing-the-docs.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc_writing-the-docs.adoc
@@ -9,6 +9,6 @@
 
 
 
-We highly recommend that you install the (IntelliJ) live templates for Asciidoctor, as described in xref:dg.adoc#__dg_ide_intellij_live-templates[IDE templates].  These provide a large number of helper templates.
+We highly recommend that you install the (IntelliJ) live templates for Asciidoctor, as described in xref:../dg/dg.adoc#__dg_ide_intellij_live-templates[IDE templates].  These provide a large number of helper templates.
 
-An xref:dg.adoc#_dg_appendix_asciidoc-templates[appendix] lists all the templates available, demonstrating their intended usage and output.
+An xref:../dg/dg.adoc#_dg_appendix_asciidoc-templates[appendix] lists all the templates available, demonstrating their intended usage and output.

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/dg/_dg_building-isis.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_building-isis.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_building-isis.adoc
index e92b0f1..5f6335b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_building-isis.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_building-isis.adoc
@@ -47,7 +47,7 @@ git clone https://git-wip-us.apache.org/repos/asf/isis.git
 ----
 
 
-If you are *not a committer*, please see the xref:dg.adoc#_dg_contributing[contributing] page for details on which repo to clone from.
+If you are *not a committer*, please see the xref:../dg/dg.adoc#_dg_contributing[contributing] page for details on which repo to clone from.
 
 
 [[__dg_building-isis_git_installation_configuring-git]]

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/dg/_dg_contributing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_contributing.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_contributing.adoc
index 88a01eb..3db485b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_contributing.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_contributing.adoc
@@ -7,7 +7,7 @@
 
 
 
-This page explains how you can contribute to Apache Isis. You'll probably also want xref:dg.adoc#_dg_ide[set up your IDE] and learn xref:dg.adoc#_dg_building-isis[how to build Apache Isis].
+This page explains how you can contribute to Apache Isis. You'll probably also want xref:../dg/dg.adoc#_dg_ide[set up your IDE] and learn xref:../dg/dg.adoc#_dg_building-isis[how to build Apache Isis].
 
 Thanks for considering to help out, your contributions are appreciated!
 
@@ -172,7 +172,7 @@ The command line prompt should also indicate you are on a branch, isolated from
 
 === Make File Changes and Commit
 
-Next, make changes to your files using the usual commands (see also our xref:dg.adoc#_dg_git-cookbook[git cookbook] section):
+Next, make changes to your files using the usual commands (see also our xref:../dg/dg.adoc#_dg_git-cookbook[git cookbook] section):
 
 * `git add`
 * `git mv`

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/dg/_dg_git-cookbook.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_git-cookbook.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_git-cookbook.adoc
index 53a126b..5cebad7 100644
--- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_git-cookbook.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_git-cookbook.adoc
@@ -10,9 +10,9 @@
 
 This appendix describes the commands often used while working with git.  In addition to these basic commands, please make sure you have read:
 
-* xref:dg.adoc#_dg_building-isis[building Apache Isis]
-* xref:dg.adoc#_dg_contributing[Contributing]
-* xref:dg.adoc#_cgcom_policies_git-policy[Git policy]
+* xref:../dg/dg.adoc#_dg_building-isis[building Apache Isis]
+* xref:../dg/dg.adoc#_dg_contributing[Contributing]
+* xref:../dg/dg.adoc#_cgcom_policies_git-policy[Git policy]
 
 
 
@@ -85,7 +85,7 @@ git commit -m "ISIS-nnn: yada yada"
 
 == Common Workflows
 
-The xref:dg.adoc#_dg_contributing[contributing] page describes the workflow for non-committers.  The xref:cgcom.adoc#_cgcom_policies_git-policy[Git policy] page describes a workflow for Apache Isis **committers**.
+The xref:../dg/dg.adoc#_dg_contributing[contributing] page describes the workflow for non-committers.  The xref:../cgcom/cgcom.adoc#_cgcom_policies_git-policy[Git policy] page describes a workflow for Apache Isis **committers**.
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_enabling-logging.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_enabling-logging.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_enabling-logging.adoc
index af3ecc3..4268586 100644
--- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_enabling-logging.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_enabling-logging.adoc
@@ -18,7 +18,7 @@ As per the http://www.datanucleus.org/products/accessplatform/logging.html[DN lo
 * In the JDBC Driver +
 +
 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:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
+There are examples of both in the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
 
 * In the database +
 +

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-to-handle-void-and-null-results.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-to-handle-void-and-null-results.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-to-handle-void-and-null-results.adoc
index 76b3a2e..373b1e6 100644
--- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-to-handle-void-and-null-results.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-to-handle-void-and-null-results.adoc
@@ -21,8 +21,8 @@ When clicking the back button in the browser the user sees "Object not found" (s
 And refresh the current page when receiving a null response or invoking a void action.
 But how to implement this?_
 
-One way to implement this idea is to provide a custom implementation of the xref:rgsvc.adoc#_rgsvc_spi_RoutingService[`RoutingService`] SPI domain service.
-The default implementation will either return the current object (if not null), else the home page (as defined by xref:rgant.adoc#_rgant-HomePage[`@HomePage`]) if one exists.
+One way to implement this idea is to provide a custom implementation of the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_RoutingService[`RoutingService`] SPI domain service.
+The default implementation will either return the current object (if not null), else the home page (as defined by xref:../rgant/rgant.adoc#_rgant-HomePage[`@HomePage`]) if one exists.
 
 The following custom implementation refines this to use the breadcrumbs (available in the Wicket viewer) to return the first non-deleted domain object found in the list of breadcrumbs:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-to-implement-a-spellchecker.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-to-implement-a-spellchecker.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-to-implement-a-spellchecker.adoc
index c141366..d165a65 100644
--- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-to-implement-a-spellchecker.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-to-implement-a-spellchecker.adoc
@@ -11,13 +11,13 @@ From this link:http://isis.markmail.org/thread/dduarjscrbnodfsi[thread] on the A
 * _What is the easiest way to add a spell checker to the text written in a field in
    a domain object, for instance to check English syntax?_
 
-One way to implement is to use the xref:rgsvc.adoc#_rgsvc_api_EventBusService[event bus]:
+One way to implement is to use the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[event bus]:
 
 * Set up a xref:rgcsm.adoc#_rgcsm_classes_domainevent[domain event] xref:rgcsm.adoc#_rgcsm_classes_super_AbstractSubscriber[subscriber] that can veto the changes.
 
-* if the change is made through an action, you can use xref:rgant.adoc#_rgant-Action_domainEvent[`@Action#domainEvent()`].
+* if the change is made through an action, you can use xref:../rgant/rgant.adoc#_rgant-Action_domainEvent[`@Action#domainEvent()`].
 
-if if the change is made through an edit, you can use xref:rgant.adoc#_rgant-Property_domainEvent[`@Property#domainEvent()`].
+if if the change is made through an edit, you can use xref:../rgant/rgant.adoc#_rgant-Property_domainEvent[`@Property#domainEvent()`].
 
 You'll need some way to know which fields should be spell checked.  Two ways spring to mind:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_i18n-label-in-wicket-viewer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_i18n-label-in-wicket-viewer.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_i18n-label-in-wicket-viewer.adoc
index 22263cd..6a6b6ac 100644
--- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_i18n-label-in-wicket-viewer.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_i18n-label-in-wicket-viewer.adoc
@@ -13,7 +13,7 @@ Referencing those via their message id inside a .po file didn't work either.
 Can this be done?_
 
 
-The above FAQ was raised against `1.10.0`.  As of `1.11.0` (due to link:https://issues.apache.org/jira/browse/ISIS-1093[ISIS-1093]) it _is_ now possible to internationalize both the Wicket viewer's labels as well as the regular translations of the domain object metadata using the `.po` translation files as supported by the xref:rgsvc.adoc#_rgsvc_spi_TranslationService[`TranslationService`].
+The above FAQ was raised against `1.10.0`.  As of `1.11.0` (due to link:https://issues.apache.org/jira/browse/ISIS-1093[ISIS-1093]) it _is_ now possible to internationalize both the Wicket viewer's labels as well as the regular translations of the domain object metadata using the `.po` translation files as supported by the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_TranslationService[`TranslationService`].
 
 Full details of the ``msgId``s that must be added to the `translations.po` file can be found in xref:guides/ugbtb.adoc#__ugbtb_i18n_wicket-viewer[i18n] section of the xref:ugbtb.adoc#[beyond the basics] guide.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_restful-image-property.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_restful-image-property.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_restful-image-property.adoc
index 3084508..a01564d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_restful-image-property.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_restful-image-property.adoc
@@ -20,6 +20,6 @@ This is in the form:
 
     (filename):(mime type):(binary data in base64)
 
-This is basically the xref:rgcms.adoc#_rgcms_classes_value-types_Blob[`Blob`] value type, in string form.
+This is basically the xref:../rgcms/rgcms.adoc#_rgcms_classes_value-types_Blob[`Blob`] value type, in string form.
 
 To use, split the parts then format the mime type and base64 data correctly before using as source in an `<img>` tag.

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_eclipse.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_eclipse.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_eclipse.adoc
index 2d310e7..a3f0dab 100644
--- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_eclipse.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_eclipse.adoc
@@ -35,7 +35,7 @@ application into Eclipse and configure to use with the JDO Objectstore.
 [[__dg_ide_eclipse_editor-templates]]
 == Editor Templates
 
-We provide a set of editor templates.  These are used to add new methods to existing classes.  (These are equivalent to the xref:dg.adoc#__dg_ide_intellij_live-templates[IntelliJ live templates]):
+We provide a set of editor templates.  These are used to add new methods to existing classes.  (These are equivalent to the xref:../dg/dg.adoc#__dg_ide_intellij_live-templates[IntelliJ live templates]):
 
 * `is` (Apache Isis domain objects).  link:./resources/eclipse/isis-templates.xml[Download]
 * `ju` (for JUnit tests) link:./resources/eclipse/junit4-templates.xml[Download]
@@ -77,7 +77,7 @@ image::{_imagesdir}eclipse/eclipse-110-project-support.png[width="600px",link="{
 
 DataNucleus' enhancer uses the domain object model's own classpath to reference DataNucleus JARs. So, even though your domain objects are unlikely to depend on DataNucleus, these references must still be present.
 
-See the earlier section on xref:ugfun.adoc#_ugfun_getting-started_datanucleus-enhancer[DataNucleus enhancer] for details of the contents of the `pom.xml`.  Chances are it is already set up from running the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
+See the earlier section on xref:../ugfun/ugfun.adoc#_ugfun_getting-started_datanucleus-enhancer[DataNucleus enhancer] for details of the contents of the `pom.xml`.  Chances are it is already set up from running the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
 
 
 Then, tell DataNucleus to use the project classpath:
@@ -171,5 +171,5 @@ Changing persisting domain entities is more problematic, for two reasons: the JD
 domain entities, and also at runtime JDO/DataNucleus would need to rebuild its own metamodel.  You may find that adding
 actions will work, but adding new properties or collections is much less likely to.
 
-For details of setting up DCEVM, see the xref:dg.adoc#__dg_ide_intellij_advanced_dcevm[corresponding section] in the IntelliJ documentation.
+For details of setting up DCEVM, see the xref:../dg/dg.adoc#__dg_ide_intellij_advanced_dcevm[corresponding section] in the IntelliJ documentation.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_intellij.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_intellij.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_intellij.adoc
index 46a6677..c458e0f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_intellij.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_intellij.adoc
@@ -148,7 +148,7 @@ The live templates have a prefix of prefixed either:
 * `is` : for Apache Isis domain objects
 * `ju` : for JUnit tests
 * `jm` : for JMock mocks or libraries
-* `ad` : for Asciidoc documentation; a full list can be found in the xref:dg.adoc#_dg_asciidoc-templates[appendix].
+* `ad` : for Asciidoc documentation; a full list can be found in the xref:../dg/dg.adoc#_dg_asciidoc-templates[appendix].
 
 The live templates are also provided as a settings JAR file, namely *link:resources/intellij/isis-settings-live-templates.jar[isis-settings-live-templates.jar]*.
 Download and import (as for the previous settings JAR files).
@@ -499,7 +499,7 @@ In this section are several options that will reduce the time it takes between m
 [[__dg_ide_intellij_advanced_gradle-compile-enhance]]
 === Using Grade to compile/enhance
 
-Running an Apache Isis application requires that the DataNucleus enhancer runs on the compiled bytecode.  As described xref:dg.adoc#__dg_ide_intellij_running_the-app[above], the recommended way to do this with IntelliJ is to use a Run configuration that runs the enhancer goal prior to launch.
+Running an Apache Isis application requires that the DataNucleus enhancer runs on the compiled bytecode.  As described xref:../dg/dg.adoc#__dg_ide_intellij_running_the-app[above], the recommended way to do this with IntelliJ is to use a Run configuration that runs the enhancer goal prior to launch.
 
 Alternative, you can use the following `build.gradle` script in your `dom` module:
 
@@ -565,7 +565,7 @@ image::{_imagesdir}intellij-idea/070-advanced/004-gradle-output.png[width="600px
 === Using Gradle for liveReload
 
 Similarly, gradle can be run to reduce the turn-around time when tweaking the UI (defined by the
- xref:ugvw.adoc#_ugvw_layout_file-based[`*.layout.xml`] file for each domain class), when the app is running.
+ xref:../ugvw/ugvw.adoc#_ugvw_layout_file-based[`*.layout.xml`] file for each domain class), when the app is running.
 
 The framework will automatically notice any changes to `.layout.xml` files, but these are read from the
 the classpath (the `target/classes` directory), not the source path.  With IntelliJ these can be copied over manually

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/dg/_dg_project-lombok.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_project-lombok.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_project-lombok.adoc
index 6a4a667..e3d7c4f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_project-lombok.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_project-lombok.adoc
@@ -33,7 +33,7 @@ private String name;
 Under the covers it is implemented as an annotation processor; it basically hooks into the Java compiler
 so that it can emit additional bytecode (eg for the getter and setter).  See xref:_cg_ide_intellij_other-settings-compiler[here] for details of setting up in IntelliJ (Eclipse has very similar support).
 
-Apache Isis supports link:https://projectlombok.org/[Project Lombok], in that the annotations that would normally be placed on the getter (namely xref:rgant.adoc#_rgant-Property[`Property`], xref:rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`], xref:rgant.adoc#_rgant-Collection[`@Collection`], xref:rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`] and xref:rgant.adoc#_rgant-MemberOrder[`@MemberOrder`]) can be placed on the field instead.
+Apache Isis supports link:https://projectlombok.org/[Project Lombok], in that the annotations that would normally be placed on the getter (namely xref:../rgant/rgant.adoc#_rgant-Property[`Property`], xref:../rgant/rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`], xref:../rgant/rgant.adoc#_rgant-Collection[`@Collection`], xref:../rgant/rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`] and xref:../rgant/rgant.adoc#_rgant-MemberOrder[`@MemberOrder`]) can be placed on the field instead.
 
 
 There are plugins for Lombok for maven; it's just a matter of adding the required dependency.  To compile the code
@@ -44,7 +44,7 @@ Lombok plugin appropriate to that IDE.  See the link:https://projectlombok.org/d
 
 == Future thoughts
 
-In the future we might extend/fork Lombok so that it understands Isis' own annotations (ie xref:rgant.adoc#_rgant-Property[`@Property`] and xref:rgant.adoc#_rgant-Collection[`@Collection`])
+In the future we might extend/fork Lombok so that it understands Isis' own annotations (ie xref:../rgant/rgant.adoc#_rgant-Property[`@Property`] and xref:../rgant/rgant.adoc#_rgant-Collection[`@Collection`])
 rather than Lombok's own `@Getter` and `@Setter.
 
 It might also be possible to use Lombok to generate the domain event classes for each member.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/dg/dg.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/dg.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/dg.adoc
index 76cd0a5..dbad10f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/dg/dg.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/dg.adoc
@@ -37,12 +37,12 @@ The user guides available are:
 
 The reference guides are:
 
-* xref:rgant.adoc#[Annotations]
-* xref:rgsvc.adoc#[Domain Services]
-* xref:rgcfg.adoc#[Configuration Properties]
-* xref:rgcms.adoc#[Classes, Methods and Schema]
-* xref:rgmvn.adoc#[Apache Isis Maven plugin]
-* xref:rgfis.adoc#[Framework Internal Services]
+* xref:../rgant/rgant.adoc#[Annotations]
+* xref:../rgsvc/rgsvc.adoc#[Domain Services]
+* xref:../rgcfg/rgcfg.adoc#[Configuration Properties]
+* xref:../rgcms/rgcms.adoc#[Classes, Methods and Schema]
+* xref:../rgmvn/rgmvn.adoc#[Apache Isis Maven plugin]
+* xref:../rgfis/rgfis.adoc#[Framework Internal Services]
 
 The remaining guides are:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action.adoc
index c0c2bac..4ee7904 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action.adoc
@@ -18,40 +18,40 @@ The table below summarizes the annotation's attributes.
 | Description
 
 
-|xref:rgant.adoc#_rgant-Action_command[`command()`]
+|xref:../rgant/rgant.adoc#_rgant-Action_command[`command()`]
 |`AS_CONFIGURED`, `ENABLED`, `DISABLED` +
 (`AS_CONFIGURED`)
 |whether the action invocation should be reified into a `o.a.i.applib.` +
-`services.command.Command` object through the xref:rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`] service.
+`services.command.Command` object through the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`] service.
 
 
 |`commandExecuteIn()`
 |`FOREGROUND`,`BACKGROUND` +
 (`FOREGROUND`)
-|whether to execute the command immediately, or to persist it (assuming that an appropriate implementation of xref:rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] has been configured) such that a background scheduler can execute the command asynchronously
+|whether to execute the command immediately, or to persist it (assuming that an appropriate implementation of xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] has been configured) such that a background scheduler can execute the command asynchronously
 
 
 |`commandPersistence()`
 |`PERSISTED`, `NOT_PERSISTED`, `IF_HINTED` +
 (`PERSISTED`)
-|whether the reified `Command` (as provided by the `CommandContext` domain service) should actually be persisted (assuming an appropriate implementation of xref:rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] has been configured).
+|whether the reified `Command` (as provided by the `CommandContext` domain service) should actually be persisted (assuming an appropriate implementation of xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] has been configured).
 
 
-|xref:rgant.adoc#_rgant-Action_domainEvent[`domainEvent()`]
+|xref:../rgant/rgant.adoc#_rgant-Action_domainEvent[`domainEvent()`]
 |subtype of `ActionDomainEvent` +
 (`ActionDomainEvent.Default`)
-|the event type to be posted to the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] to
+|the event type to be posted to the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] to
 broadcast the action's business rule checking (hide, disable, validate) and its invocation (pre-execute and
 post-execute).
 
 
-|xref:rgant.adoc#_rgant-Action_hidden[`hidden()`]
+|xref:../rgant/rgant.adoc#_rgant-Action_hidden[`hidden()`]
 |`EVERYWHERE`, `NOWHERE` +
 (`NOWHERE`)
 |indicates where (in the UI) the action should be hidden from the user.
 
 
-|xref:rgant.adoc#_rgant-Action_invokeOn[`invokeOn()`]
+|xref:../rgant/rgant.adoc#_rgant-Action_invokeOn[`invokeOn()`]
 |`OBJECT_ONLY`, `COLLECTION_ONLY`, `OBJECT_AND_COLLECTION` +
 (`OBJECT_ONLY`)
 |whether an action can be invoked on a single object and/or on many objects in a collection.
@@ -59,22 +59,22 @@ post-execute).
 Currently this is only supported for no-arg actions.
 
 
-|xref:rgant.adoc#_rgant-Action_publishing[`publishing()`]
+|xref:../rgant/rgant.adoc#_rgant-Action_publishing[`publishing()`]
 |`AS_CONFIGURED`, `ENABLED`, `DISABLED` +
 (`AS_CONFIGURED`)
-|whether the action invocation should be published to the registered xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`].
+|whether the action invocation should be published to the registered xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`].
 
 |`publishing-` +
 `PayloadFactory()`
 |subtype of `PublishingPayloadFactory-` `ForAction` (none)
 |specifies that a custom implementation of `PublishingPayloadFactoryForAction` be used to create the (payload of the) published event representing the action invocation
 
-|xref:rgant.adoc#_rgant-Action_restrictTo[`restrictTo()`]
+|xref:../rgant/rgant.adoc#_rgant-Action_restrictTo[`restrictTo()`]
 |`NO_RESTRICTIONS`,`PROTOTYPING` +
 (`NO_RESTRICTIONS`)
 |whether the action is only available in prototyping mode, or whether it is available also in production mode.
 
-|xref:rgant.adoc#_rgant-Action_semantics[`semantics()`]
+|xref:../rgant/rgant.adoc#_rgant-Action_semantics[`semantics()`]
 |`SAFE_AND_REQUEST_CACHEABLE`, `SAFE`, +
 `IDEMPOTENT`, `IDEMPOTENT_ARE_YOU_SURE` +
 `NON_IDEMPOTENT`, `NON_IDEMPOTENT_ARE_YOU_SURE` + +
@@ -83,7 +83,7 @@ Currently this is only supported for no-arg actions.
 
 The `...ARE_YOU_SURE` variants cause a confirmation dialog to be displayed in the xref:ugvw.adoc#[Wicket viewer].
 
-|xref:rgant.adoc#_rgant-Action_typeOf[`typeOf()`]
+|xref:../rgant/rgant.adoc#_rgant-Action_typeOf[`typeOf()`]
 |(none)
 |if the action returns a collection, hints as to the run-time type of the objects within that collection (as a fallback)
 

[46/58] [abbrv] isis git commit: ISIS-1521: further minor updates to ugfun.adoc

[da...@apache.org]

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_properties.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_properties.adoc
new file mode 100644
index 0000000..540ada1
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_properties.adoc
@@ -0,0 +1,411 @@
+[[_ugfun_class-structure_properties]]
+= Property
+: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/
+
+
+A property is an instance variable of a domain object, of a scalar type, that holds some state about either a xref:../ugfun/ugfun.adoc#__ugfun_class-structure_class-definition_entities[domain entity] or a xref:../ugfun/ugfun.adoc#__ugfun_class-structure_class-definition_view-models[view model].
+
+For example, a ``Customer``'s `firstName` would be a property, as would their `accountCreationDate` that they created their account.
+All properties have at least a "getter" method, and most properties have also a "setter" method (meaning that they are mutable).
+Properties that do _not_ have a setter method are derived properties, and so are not persisted.
+
+Formally speaking, a property is simply a regular JavaBean getter, returning a scalar value recognized by the framework.
+Most properties (those that are editable/modifiable) will also have a setter and (if persisted) a backing instance field.
+And most properties will also have a number of annotations:
+
+* Apache Isis defines its own set own `@Property` annotation for capturing domain semantics.
+It also provides a `@PropertyLayout` for UI hints (though the information in this annotation may instead be provided by a supplementary xref:../ugvw/ugvw.adoc#_ugvw_layout[`.layout.xml`] file
+
+* the properties of domain entities are often annotated with the JDO/DataNucleus `@javax.jdo.annotations.Column` annotation.
+For property references, there may be other annotations to indicate whether the reference is bidirectional.
+It's also possible (using annotations) to define a link table to hold foreign key columns.
+
+* for the properties of view models, then JAXB annotations such as `@javax.xml.bind.annotation.XmlElement` will be present
+
+Apache Isis recognises some of these annotations for JDO/DataNucleus and JAXB and infers some domain semantics from them (for example, the maximum allowable length of a string property).
+
+Since writing getter and setter methods adds quite a bit of boilerplate, it's common to use link:https://projectlombok.org/[Project Lombok] to code generate these methods at compile time (using Java's annotation processor) simply by adding the `@lombok.Getter` and `@lombok.Setter` annotations to the field.
+The xref:guides/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] uses this approach.
+
+
+[[__ugfun_class-structure_properties_value-vs-reference-types]]
+== Value vs Reference Types
+
+Properties can be either a value type (strings, int, date and so on) or be a reference to another object (for example, an `Order` referencing the `Customer` that placed it).
+
+For example, to map a string value type:
+
+[source,java]
+----
+@lombok.Getter @lombok.Setter       // <1>
+private String notes;
+----
+<1> using link:https://projectlombok.org/[Project Lombok] annotations to reduce boilerplate
+
+You could also add the `@Property` annotation if you wished:
+
+[source,java]
+----
+@Property
+@lombok.Getter @lombok.Setter
+private String notes;
+----
+
+Although in this case it is not required (none of its attributes have been set).
+
+Or to map a reference type:
+
+[source,java]
+----
+@lombok.Getter @lombok.Setter
+private Customer customer;
+----
+
+It's ok for a xref:../ugfun/ugfun.adoc#__ugfun_class-structure_class-definition_entities[domain entity] to reference another domain entity, and for a xref:../ugfun/ugfun.adoc#__ugfun_class-structure_class-definition_view-models[view model] to reference both view model and domain entities.
+However, it isn't valid for a domain entity to hold a persisted reference to view model (DataNucleus will not know how to persist that view model).
+
+[NOTE]
+====
+For further details on mapping associations, see the JDO/DataNucleus documentation for link:http://www.datanucleus.org/products/accessplatform_4_1/jdo/orm/one_to_many.html[one-to-many] associations, link:http://www.datanucleus.org/products/accessplatform_4_1/jdo/orm/many_to_one.html[many-to-one] associations, link:http://www.datanucleus.org/products/accessplatform_4_1/jdo/orm/many_to_many.html[many-to-many] associations, and so on.
+====
+
+For domain entities, the annotations for mapping value types tend to be different for properties vs action parameters, because JDO annotations are only valid on properties.
+The table in the xref:../ugfun/ugfun.adoc#_ugfun_class-structure_properties-vs-parameters[Properties vs Parameters] section provides a handy reference of each.
+
+
+[[__ugfun_class-structure_properties_optional-properties]]
+== Optional Properties
+
+(For domain entities) JDO/DataNucleus' default is that a property is assumed to be mandatory if it is a primitive type (eg `int`, `boolean`), but optional if a reference type (eg `String`, `BigDecimal` etc).
+To override optionality in JDO/DataNucleus the `@Column(allowsNull="...")` annotations is used.
+
+Apache Isis on the other hand assumes that all properties (and action parameters, for that matter) are mandatory, not optional.
+These defaults can also be overridden using Apache Isis' own annotations, specifically `@Property(optionality=...)`, or (because it's much less verbose) using `@javax.annotation.Nullable`.
+
+These different defaults can lead to incompatibilities between the two frameworks.
+To counteract that, Apache Isis also recognizes and honours JDO's `@Column(allowsNull=...)`.
+
+For example, you can write:
+
+[source,java]
+----
+@javax.jdo.annotations.Column(allowsNull="true")
+@lombok.Getter @lombok.Setter
+private LocalDate date;
+----
+
+rather than the more verbose:
+
+[source,java]
+----
+@javax.jdo.annotations.Column(allowsNull="true")
+@Property(optionality=Optionality.OPTIONAL)
+@lombok.Getter @lombok.Setter
+private LocalDate date;
+----
+
+The framework will search for any incompatibilities in optionality (whether specified explicitly or defaulted implicitly) between Isis' defaults and DataNucleus, and refuse to boot if any are found (fail fast).
+
+[[__ugfun_class-structure_properties_editable-properties]]
+== Editable Properties
+
+Apache Isis provides the capability to allow individual properties to be modified.
+This is specified using the `@Property(editing=...)` attribute.
+
+For example:
+
+[source,java]
+----
+@Property(editing = Editing.ENABLED)
+@lombok.Getter @lombok.Setter
+private String notes;
+----
+
+If this is omitted then whether editing is enabled or disabled is defined globally, in the `isis.properties` configuration file; see xref:../rgcfg/rgcfg.adoc#__rgcfg_configuring-core_isis-objects-editing[reference configuration guide] for further details.
+
+
+[[__ugfun_class-structure_properties_ignoring-properties]]
+== Ignoring Properties
+
+By default Apache Isis will automatically render all properties in the xref:../ugvw/ugvw.adoc[UI] or in the xref:../ugvro/ugvro.adoc[REST API].
+To get Apache Isis to ignore a property (exclude it from its metamodel), annotate the getter using `@Programmatic`.
+
+Similarly, you can tell JDO/DataNucleus to ignore a property using the `@javax.jdo.annotations.NotPersistent` annotation.
+This is independent of Apache Isis; in other words that property will still be rendered in the UI (unless also annotated with `@Programmatic`).
+
+For view models, you can tell JAXB to ignore a property using the `@javax.xml.bind.annotation.XmlTransient` annotation.
+Again, this is independent of Apache Isis.
+
+
+[[__ugfun_class-structure_properties_derived-properties]]
+== Derived Properties
+
+Derived properties are those with a getter but no setter.
+Provided that the property has not been annotated with `@Programmatic`, these will still be rendered in the UI, but they will be read-only (not editable) and their state will not be persisted.
+
+Subtly different, it is also possible to have non-persisted but still editable properties.
+In this case you will need a getter and a setter, but with the getter annotated using `@NotPersistent`.
+The implementation of these getters and setters will most likely persist state using other properties (which might be hidden from view using `@Programmatic`).
+
+For example:
+
+[source,java]
+----
+@javax.jdo.annotations.NotPersistent
+@Property(editing=Editing.ENABLED)
+public String getAddress() { return addressService.toAddress( getLatLong() ); }             // <1>
+public void setAddress(String address) { setLatLong(addressService.toLatLong(address)); }
+
+@javax.jdo.annotations.Column
+private String latLong;
+@Programmatic
+public String getLatLong() { return latLong; }                                              // <2>
+public void setLatLong(String latLong) { this.latLong = latLong; }
+
+@javax.inject.Inject
+AddressService addressService;                                                              // <3>
+----
+<1> the representation of the address, in human readable form, eg "10 Downing Street, London, UK"
+<2> the lat/long representation of the address, eg "51.503363;-0.127625"
+<3> an injected service that can convert to/from address and latLong.
+
+
+
+[[__ugfun_class-structure_properties_datatypes]]
+== Data types
+
+This section shows specific considerations for various datatypes, in particular how to annotate them for DataNucleus mapping to the persistence object store.
+
+
+
+[[__ugfun_class-structure_properties_datatypes_strings]]
+=== ``String``s (Length)
+
+By default JDO/DataNucleus will map string properties to a `VARCHAR(255)`.
+To limit the length, use the `@Column(length=...)` annotation.
+
+For example:
+
+[source,java]
+----
+@javax.jdo.annotations.Column(length=50)
+@lombok.Getter @lombok.Setter
+private String firstName
+----
+
+This is a good example of a case where Apache Isis infers domain semantics from the JDO annotation.
+
+
+
+[[__ugfun_class-structure_properties_datatypes-joda-dates]]
+=== JODA Dates
+
+Isis' JDO objectstore bundles DataNucleus' http://www.datanucleus.org/documentation/products/plugins.html[built-in support] for Joda `LocalDate` and `LocalDateTime` datatypes, meaning that entity properties of these types will be persisted as appropriate data types in the database tables.
+
+It is, however, necessary to annotate your properties with `@javax.jdo.annotations.Persistent`, otherwise the data won't actually be persisted.
+See the link:http://db.apache.org/jdo/field_types.html[JDO docs] for more details on this.
+
+Moreover, these datatypes are _not_ in the default fetch group, meaning that JDO/DataNucleus will perform an additional `SELECT` query for each attribute.
+To avoid this extra query, the annotation should indicate that the property is in the default fetch group.
+
+For example, the `ToDoItem` (in the https://github.com/isisaddons/isis-app-todoapp[todoapp example app] (not ASF)) defines the `dueBy` property as follows:
+
+[source,java]
+----
+@javax.jdo.annotations.Persistent(defaultFetchGroup="true")
+@javax.jdo.annotations.Column(allowsNull="true")
+@Getter @Setter
+private LocalDate dueBy;
+----
+
+
+[[__ugfun_class-structure_properties_datatypes_bigdecimals]]
+=== ``BigDecimal``s (Precision)
+
+Working with `java.math.BigDecimal` properties takes a little care due to scale/precision issues.
+
+For example, suppose we have:
+
+[source,java]
+----
+@lombok.Getter @lombok.Setter
+private BigDecimal impact;
+----
+
+JDO/DataNucleus creates, at least with HSQL, the table with the field type as NUMERIC(19). No decimal digits are admitted. (Further details http://hsqldb.org/doc/2.0/guide/sqlgeneral-chapt.html#sgc_numeric_types[here]).
+
+What this implies is that, when a record is inserted, a log entry similar to this one appears:
+
+[source,java]
+----
+INSERT INTO ENTITY(..., IMPACT, ....) VALUES (...., 0.5, ....)
+----
+
+But when that same record is retrieved, the log will show that a value of "0" is returned, instead of 0.5.
+
+The solution is to explicitly add the scale to the field like this:
+
+[source,java]
+----
+@javax.jdo.annotations.Column(scale=2)
+@lombok.Getter @lombok.Setter
+private BigDecimal impact;
+----
+
+In addition, you should also set the scale of the `BigDecimal`, using `setScale(scale, roundingMode)`.
+
+More information can be found http://www.opentaps.org/docs/index.php/How_to_Use_Java_BigDecimal:_A_Tutorial[here] and http://www.tutorialspoint.com/java/math/bigdecimal_setscale_rm_roundingmode.htm[here].
+
+
+
+[[__ugfun_class-structure_properties_datatypes_blobs]]
+=== ``Blob``s
+
+Apache Isis configures JDO/DataNucleus so that the properties of type `org.apache.isis.applib.value.Blob` and `org.apache.isis.applib.value.Clob` can also be persisted.
+
+As for xref:../ugfun/ugfun.adoc#__ugfun_class-structure_properties_datatypes_joda-dates[Joda dates], this requires the `@javax.jdo.annotations.Persistent` annotation.
+However, whereas for dates one would always expect this value to be retrieved eagerly, for blobs and clobs it is not so clear cut.
+
+For example, in the `ToDoItem` class (of the https://github.com/isisaddons/isis-app-todoapp/blob/0333852ddd18ad67e3356fccf805aa442246790d/dom/src/main/java/todoapp/dom/todoitem/ToDoItem.java#L442[todoapp example app] (non-ASF) the `attachment` property is as follows:
+
+[source,java]
+----
+@javax.jdo.annotations.Persistent(defaultFetchGroup="false", columns = {
+    @javax.jdo.annotations.Column(name = "attachment_name"),
+    @javax.jdo.annotations.Column(name = "attachment_mimetype"),
+    @javax.jdo.annotations.Column(name = "attachment_bytes", jdbcType="BLOB", sqlType = "LONGVARBINARY")
+})
+@Property(
+        optionality = Optionality.OPTIONAL
+)
+@lombok.Getter @lombok.Setter
+private Blob attachment;
+----
+
+The three `@javax.jdo.annotations.Column` annotations are required because the mapping classes that Apache Isis provides (https://github.com/apache/isis/blob/isis-1.4.0/component/objectstore/jdo/jdo-datanucleus/src/main/java/org/apache/isis/objectstore/jdo/datanucleus/valuetypes/IsisBlobMapping.java#L59[IsisBlobMapping] and https://github.com/apache/isis/blob/isis-1.4.0/component/objectstore/jdo/jdo-datanucleus/src/main/java/org/apache/isis/objectstore/jdo/datanucleus/valuetypes/IsisClobMapping.java#L59[IsisClobMapping]) map to 3 columns.
+(It is not an error to omit these `@Column` annotations, but without them the names of the table columns are simply suffixed `_0`, `_1`, `_2` etc.
+
+If the `Blob` is mandatory, then use:
+
+[source,java]
+----
+@javax.jdo.annotations.Persistent(defaultFetchGroup="false", columns = {
+    @javax.jdo.annotations.Column(name = "attachment_name", allowsNull="false"),
+    @javax.jdo.annotations.Column(name = "attachment_mimetype", allowsNull="false"),
+    @javax.jdo.annotations.Column(name = "attachment_bytes",
+                                  jdbcType="BLOB", sqlType = "LONGVARBINARY",
+                                  allowsNull="false")
+})
+@Property(
+    optionality = Optionality.MANDATORY
+)
+@lombok.Getter @lombok.Setter
+private Blob attachment;
+----
+
+[NOTE]
+====
+If specifying a `sqlType` of "LONGVARBINARY" does not work, try instead "BLOB".
+There can be differences in behaviour between JDBC drivers.
+====
+
+[[__ugfun_class-structure_properties_datatypes_clobs]]
+=== ``Clob``s
+
+
+Mapping `Clob`s works in a very similar way to xref:../ugfun/ugfun.adoc#__ugfun_class-structure_properties_datatypes_blobs[``Blob``]s, but the `jdbcType` and `sqlType` attributes will, respectively, be `CLOB` and `LONGVARCHAR`:
+
+[source,java]
+----
+@javax.jdo.annotations.Persistent(defaultFetchGroup="false", columns = {
+    @javax.jdo.annotations.Column(name = "attachment_name"),
+    @javax.jdo.annotations.Column(name = "attachment_mimetype"),
+    @javax.jdo.annotations.Column(name = "attachment_chars",
+                                  jdbcType="CLOB", sqlType = "LONGVARCHAR")
+})
+private Clob doc;
+@Property(
+    optionality = Optionality.OPTIONAL
+)
+public Clob getDoc() {
+    return doc;
+}
+public void setDoc(final Clob doc) {
+    this.doc = doc;
+}
+----
+
+[NOTE]
+====
+If specifying a `sqlType` of "LONGVARCHAR" does not work, try instead "CLOB".  There can be differences in behaviour between JDBC drivers.
+====
+
+
+[[__ugfun_class-structure_properties_datatypes_mapping-to-varbinary-or-varchar]]
+=== Mapping to VARBINARY or VARCHAR
+
+Instead of mapping to a sqlType of `LONGVARBINARY` (or perhaps `BLOB`), you might instead decide to map to a `VARBINARY`.
+The difference is whether the binary data is held "on-row" or as a pointer "off-row"; with a `VARBINARY` the data is held on-row and so you will need to specify a length.
+
+For example:
+
+[source,java]
+----
+@javax.jdo.annotations.Column(name = "attachment_bytes", jdbcTypr="BLOB", sqlType = "VARBINARY", length=2048)
+----
+
+The same argument applies to `LONGVARCHAR` (or `CLOB`); you could instead map to a regular `VARCHAR`:
+
+[source,java]
+----
+@javax.jdo.annotations.Column(name = "attachment_chars", sqlType = "VARCHAR", length=2048)
+----
+Support and maximum allowed length will vary by database vendor.
+
+
+
+[[__ugfun_class-structure_properties_handling-mandatory-properties-in-subtypes]]
+== Handling Mandatory Properties in Subtypes
+
+
+NOTE: FIXME - move to ugodn.adoc#_ugodn_hints-and-tips
+
+
+If you have a hierarchy of classes then you need to decide which inheritance strategy to use.
+
+* "table per hierarchy", or "rollup" (`InheritanceStrategy.SUPERCLASS_TABLE`) +
++
+whereby a single table corresponds to the superclass, and also holds the properties of the subtype (or subtypes) being rolled up
+
+* "table per class" (`InheritanceStrategy.NEW_TABLE`) +
++
+whereby there is a table for both superclass and subclass, in 1:1 correspondence
+
+* "rolldown" (`InheritanceStrategy.SUBCLASS_TABLE`) +
++
+whereby a single table holds the properties of the subtype, and also holds the properties of its supertype
+
+In the first "rollup" case, we can have a situation where - logically speaking - the property is mandatory in the subtype - but it must be mapped as nullable in the database because it is n/a for any other subtypes that are rolled up.
+
+In this situation we must tell JDO that the column is optional, but to Apache Isis we want to enforce it being mandatory. This can be done using the `@Property(optionality=Optionality.MANDATORY)` annotation.
+
+For example:
+
+[source,java]
+----
+@javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.SUPER_TABLE)
+public class SomeSubtype extends SomeSuperType {
+    @javax.jdo.annotations.Column(allowsNull="true")
+    @Property(optionality=Optionality.MANDATORY)
+    @lombok.Getter @lombok.Setter
+    private LocalDate date;
+}
+----
+
+[TIP]
+====
+The `@Property(optionality=...)` annotation is equivalent to the older but still supported `@Optional` annotation and `@Mandatory` annotations.
+====
+

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud.adoc
new file mode 100644
index 0000000..247deaf
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud.adoc
@@ -0,0 +1,29 @@
+[[_ugfun_crud]]
+= Object Management (CRUD)
+: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/
+
+NOTE: FIXME
+
+
+## Instantiating and Persisting
+
+NOTE: FIXME - using ``DomainObjectContainer``'s support for  xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-creation-api[creation] and xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-persistence-api[persistence]
+
+## Finding Objects
+
+NOTE: FIXME - using xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer_generic-repository-api[`DomainObjectContainer`]
+
+### Using DataNucleus type-safe queries
+
+NOTE: FIXME - as described xref:../rgsvc/rgsvc.adoc#__rgsvc_api_IsisJdoSupport_type-safe-jdoql-queries[here]
+
+
+
+## Deleting Objects
+
+NOTE: FIXME using ``DomainObjectContainer``'s support for  xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-persistence-api[persistence]
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology.adoc
new file mode 100644
index 0000000..7e496a0
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology.adoc
@@ -0,0 +1,43 @@
+[[_ugfun_domain-class-ontology]]
+= Domain Class Ontology
+: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 supports recognises three main types of domain classes:
+
+* domain entities - domain objects persisted to the database using JDO/DataNucleus; for example `Customer`
+
+* domain services - generally singletons, automatically injected, and providing various functionality; for example `CustomerRepository`
+
+* view models - domain objects that are a projection of some state held by the database, in support a particular use case; for example `CustomerDashboard` (to pull together commonly accessed information about a customer).
+
+Domain classes are generally recognized using annotations.
+Apache Isis defines its own set of annotations, while entities are annotated using JDO/DataNucleus (though XML can also be used if required).
+JAXB can also be used for view models.
+Apache Isis recognizes some of the JDO and JAXB annotations and infers domain semantics from these annotations.
+
+You can generally recognize an Apache Isis domain class because it will be probably be annotated using `@DomainObject` and `@DomainService`.
+The framework also defines supplementary annotations, `@DomainObjectLayout` and `@DomainServiceLayout`.
+These provide hints relating to the layout of the domain object in the user interface.
+(Alternatively, these UI hints can be defined in a supplementary xref:../ugvw/ugvw.adoc#_ugvw_layout[`.layout.xml`] file.
+
+We use Maven modules as a way to group related domain objects together; we can then reason about all the classes in that module as a single unit.
+By convention there will be a single top-level package corresponding to the module.
+
+For example, the (non-ASF) link:https://github.com/incodehq/incode-module-document[Document module] (part of the link:http://catalog.incode.org[Incode Catalog]) has a top-level package of `org.incode.module.document`.
+Within the module there may be various subpackages, but its the module defines the namespace.
+
+In the same way that the Java module act as a namespace for domain objects, it's good practice to map domain entities to their own (database) schemas.
+
+
+
+include::_ugfun_domain-class-ontology_domain-entities.adoc[leveloffset=+1]
+include::_ugfun_domain-class-ontology_domain-services.adoc[leveloffset=+1]
+include::_ugfun_domain-class-ontology_view-models.adoc[leveloffset=+1]
+
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_domain-entities.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_domain-entities.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_domain-entities.adoc
new file mode 100644
index 0000000..ce399e3
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_domain-entities.adoc
@@ -0,0 +1,86 @@
+[[_ugfun_domain-class-ontology_domain-entities]]
+= Domain Entities
+: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/
+
+
+
+Entities are persistent domain objects, with their persistence handled by JDO/DataNucleus.
+As such, they are mapped to a persistent object store, typically an RDBMS, with DataNucleus taking care of both lazy loading and also the persisting of modified ("dirty") objects.
+
+Domain entities are generally decorated with both DataNucleus and Apache Isis annotations.
+The following is typical:
+
+[source,java]
+----
+@javax.jdo.annotations.PersistenceCapable(                                      // <1>
+        identityType=IdentityType.DATASTORE,                                    // <2>
+        schema = "simple",                                                      // <3>
+        table = "SimpleObject"
+)
+@javax.jdo.annotations.DatastoreIdentity(                                       // <4>
+        strategy=javax.jdo.annotations.IdGeneratorStrategy.IDENTITY,
+        column="id"
+)
+@javax.jdo.annotations.Version(                                                 // <5>
+        strategy= VersionStrategy.DATE_TIME,
+        column="version"
+)
+@javax.jdo.annotations.Queries({
+        @javax.jdo.annotations.Query(                                           // <6>
+                name = "findByName",
+                value = "SELECT "
+                        + "FROM domainapp.modules.simple.dom.impl.SimpleObject "
+                        + "WHERE name.indexOf(:name) >= 0 ")
+})
+@javax.jdo.annotations.Unique(name="SimpleObject_name_UNQ", members = {"name"}) // <7>
+@DomainObject(                                                                  // <8>
+        objectType = "simple.SimpleObject"
+)
+public class SimpleObject
+             implements Comparable<SimpleObject> {                              // <9>
+
+    public SimpleObject(final String name) {                                    // <10>
+        setName(name);
+    }
+
+    ...
+
+    @Override
+    public String toString() {
+        return ObjectContracts.toString(this, "name");                          // <11>
+    }
+    @Override
+    public int compareTo(final SimpleObject other) {
+        return ObjectContracts.compare(this, other, "name");                    // <9>
+    }
+}
+----
+<1> The `@PersistenceCapable` annotation indicates that this is an entity to DataNucleus.
+The DataNucleus enhancer acts on the bytecode of compiled entities, injecting lazy loading and dirty object tracking functionality.
+Enhanced entities end up also implementing the `javax.jdo.spi.PersistenceCapable` interface.
+<2> Indicates how identifiers for the entity are handled.
+Using `DATASTORE` means that a DataNucleus is responsible for assigning the value (rather than the application).
+<3> Specifies the RDBMS database schema and table name for this entity will reside.
+The schema should correspond with the module in which the entity resides.
+The table will default to the entity name if omitted.
+<4> For entities that are using `DATASTORE` identity, indicates how the id will be assigned.
+A common strategy is to allow the database to assign the id, for example using an identity column or a sequence.
+<5> The `@Version` annotation is useful for optimistic locking; the strategy indicates what to store in the `version` column.
+<6> The `@Query` annotation (usually several of them, nested within a `@Queries` annotation) defines queries using JDOQL.
+DataNucleus provides several APIs for defining queries, including entirely programmatic and type-safe APIs; but JDOQL is very similar to SQL and so easily learnt.
+<7> DataNucleus will automatically add a unique index to the primary surrogate id (discussed above), but additional alternative keys can be defined using the `@Unique` annotation.
+In the example above, the "name" property is assumed to be unique.
+<8> The `@DomainObject` annotation identifies the domain object to Apache Isis (not DataNucleus).
+It isn't necessary to include this annotation -- at least, not for entities -- but it is nevertheless recommended.
+In particular, its strongly recommended that the `objectType` (which acts like an alias to the concrete domain class) is specified; note that it corresponds to the schema/table for DataNucleus' `@PersistenceCapable` annotation.
+<9> Although not required, we strongly recommend that all entities are naturally `Comparable`.
+This then allows parent/child relationships to be defined using ``SortedSet``s; RDBMS after all are set-oriented.
+The `ObjectContracts` utility class provided by Apache Isis makes it easy to implement the `compareTo()` method, but you can also just use an IDE to generate an implementation or roll your own.
+<10> Chances are that some of the properties of the entity will be mandatory, for example any properties that represent an alternate unique key to the entity.
+In regular Java programming we would represent this using a constructor that defines these mandatory properties, and in Apache Isis/DataNucleus we can likewise define such a constructor.
+When DataNucleus rehydrates domain entities from the database at runtime, it actually requires a no-arg constructor (it then sets all state reflectively).
+However, there is no need to provide such a no-arg constructor; it is added by the enhancer process.
+<11> The `ObjectContracts` utility class also provides assistance for `toString()`, useful when debugging in an IDE.
+

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_domain-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_domain-services.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_domain-services.adoc
new file mode 100644
index 0000000..e89b754
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_domain-services.adoc
@@ -0,0 +1,214 @@
+[[_ugfun_domain-class-ontology_domain-services]]
+= Domain Services
+: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/
+
+
+In Apache Isis domain services have several responsibilities:
+
+- to expose actions to be rendered in the menu
+- to provide actions that are rendered as contributed actions/properties/collections on the contributee domain object
+- they act as subscribers to the event bus
+- they act as repositories (find existing objects) or as factories (create new objects)
+- they provide other services (eg performing calculations, attach a barcode, send an email etc).
+- to implement an SPI of the framework, most notably cross-cutting concerns such as security, command profiling, auditing and publishing.
+
+It's worth extending the xref:../ugfun/ugfun.adoc#_ugfun_core-concepts_philosophy_hexagonal-architecture[Hexagonal Architecture] to show where domain services -- and in particular the domain services provided by link:http://www.isisaddons.org[Isis Addons] (non-ASF) -- fit in:
+
+.The hexagonal architecture with Isis addons
+image::{_imagesdir}how-tos/domain-services/hexagonal-architecture-addons.png[width="700px"]
+
+The (non-ASF) link:http://isisaddons.org[Isis Addons] are a good source of domain services, providing SPI implementations of the common cross-cutting concerns, and also a number of APIs for domain objects to invoke (eg tags, excel, settings).  Of course, you can also write your own domain services as well, for example to interface with some external CMS system, say.
+
+
+
+[[__ugfun_domain-class-ontology_domain-services_organizing-services]]
+== Organizing Services
+
+In larger applications we have found it worthwhile to ensure that our domain services only act aligned with these responsibilities, employing a naming convention so that it is clear what the responsibilities of each domain service is.
+
+The application provides the `@DomainService(nature=...)` annotation that helps distinguish some of these responsibilities:
+
+- `VIEW` indicates that the actions should appear both on the menu and also be used as contributions
+- `VIEW_MENU_ONLY` indicates that the actions should appear on the menu
+- `VIEW_CONTRIBUTIONS_ONLY` indicates that the actions should not appear on the menu
+- `DOMAIN` indicates that the actions are for other domain objects to invoke (either directly or indirectly through the event bus), but in any case should not be rendered at all in the UI
+
+Pulling all the above together, here are our suggestions as to how you should organize your domain services.
+
+
+=== Factory and Repository
+
+The factory/repository uses an injected `DomainObjectContainer` to both instantiate new objects and to query the database for existing objects of a given entity type.  It is not visible in UI, rather other services delegate to it.
+
+We suggest naming such classes `XxxRepository`, eg:
+
+
+[source,java]
+----
+@DomainService(
+    nature=NatureOfService.DOMAIN                               // <1>
+)
+public CustomerRepository {
+    public List<Customer> findCustomerBy...(...) {
+        return allMatches(...);
+    }
+    public Customer newCustomer(...) {
+        Customer Customer = container.newTransientInstance(Customer.class);
+        ...
+        persistIfNotAlready(Customer);
+        return Customer;
+    }
+    public List<Customer> allCustomers() {
+        return container.allInstances(Customer.class);
+    }
+    @Inject
+    DomainObjectContainer container;
+}
+----
+<1> interacted with only programmatically by other objects in the domain layer.
+
+There is no need to annotate the actions; they are implicitly hidden because of the domain service's nature.
+
+
+
+=== Menu
+
+Menu services provide actions to be rendered on the menu.
+
+For the Wicket viewer, each service's actions appear as a collection of menu items of a named menu, and this menu is on one of the three menu bars provided by the Wicket viewer.  It is possible for more than one menu service's actions to appear on the same menu; a separator is shown between each.
+
+For the Restful Objects viewer, all menu services are shown in the services representation.
+
+We suggest naming such classes `XxxMenu`, eg:
+
+
+[source,java]
+----
+@DomainService(
+    nature = NatureOfService.VIEW_MENU_ONLY                     // <1>
+)
+@DomainServiceLayout(
+        named = "Customers",                                    // <2>
+        menuBar = DomainServiceLayout.MenuBar.PRIMARY,
+        menuOrder = "10"
+)
+public class CustomerMenu {
+    @Action(
+            semantics = SemanticsOf.SAFE
+    )
+    @MemberOrder( sequence = "1" )
+    public List<Customer> findCustomerBy...(...) {
+        return customerRepository.findCustomerBy(...);          // <3>
+    }
+
+    @Action(
+            semantics = SemanticsOf.NON_IDEMPOTENT
+    )
+    @MemberOrder( sequence = "3" )
+    public Customer newCustomer(...) {
+        return customerRepository.newCustomer(...);
+    }
+
+    @Action(
+            semantics = SemanticsOf.SAFE,
+            restrictTo = RestrictTo.PROTOTYPING
+    )
+    @MemberOrder( sequence = "99" )
+    public List<Customer> allCustomers() {
+        return customerRepository.allBankMandates();
+    }
+
+    @Inject
+    protected CustomerRepository customerRepository;
+}
+----
+<1> the service's actions should be rendered as menu items
+<2> specifies the menu name.  All services with the same menu name will be displayed on the same menu, with separators between
+<3> delegates to an injected repository.
+
+Not every action on the repository need to be delegated to of course (the above example does but only because it is very simple).
+
+[TIP]
+====
+Note also that while there's nothing to stop `VIEW_MENU` domain services being injected into other domain objects and interacted with programmatically, we recommend against it.  Instead, inject the underlying repository.  If there is additional business logic, then consider introducing a further `DOMAIN`-scoped service and call that instead.
+====
+
+
+
+=== Contributions
+
+Services can contribute either actions, properties or collections, based on the type of their parameters.
+
+We suggest naming such classes `XxxContributions`, eg:
+
+[source,java]
+----
+@DomainService(
+    nature=NatureOfService.VIEW_CONTRIBUTIONS_ONLY              // <1>
+)
+@DomainServiceLayout(
+    menuOrder="10",
+    name="...",
+}
+public OrderContributions {
+    @Action(semantics=SemanticsOf.SAFE)
+    @ActionLayout(contributed=Contributed.AS_ASSOCIATION)       // <2>
+    @CollectionLayout(render=RenderType.EAGERLY)
+    public List<Order> orders(Customer customer) {              // <3>
+        return container.allMatches(...);
+    }
+
+    @Inject
+    CustomerRepository customerRepository;
+}
+----
+<1> the service's actions should be contributed to the entities of the parameters of those actions
+<2> contributed as an association, in particular as a collection because returns a `List<T>`.
+<3> Only actions with a single argument can be contributed as associations
+
+More information about contributions can be found xref:../ugfun/ugfun.adoc#_ugfun_how-tos_contributed-members[here].  More information
+about using contributions and mixins to keep your domain application decoupled can be found xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_contributions[here] and xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_mixins[here].
+
+
+=== Event Subscribers
+
+Event subscribers can both veto interactions (hiding members, disabling members or validating changes), or can react to interactions (eg action invocation or property edit).
+
+We suggest naming such classes `XxxSubscriptions`, eg:
+
+[source,java]
+----
+@DomainService(
+    nature=NatureOfService.DOMAIN                       // <1>
+)
+@DomainServiceLayout(
+    menuOrder="10",
+    name="...",
+}
+public CustomerOrderSubscriptions {
+    @com.google.common.eventbus.Subscribe
+    public void on(final Customer.DeletedEvent ev) {
+        Customer customer = ev.getSource();
+        orderRepository.delete(customer);
+    }
+    @Inject
+    OrderRepository orderRepository;
+}
+----
+<1> subscriptions do not appear in the UI at all, so should use the domain nature of service
+
+
+
+== Prototyping
+
+While for long-term maintainability we do recommend the naming conventions described xref:../ugfun/ugfun.adoc#__ugfun_domain-class-ontology_domain-services_organizing-services[above], you can get away with far fewer services when just prototyping a domain.
+
+If the domain service nature is not specified (or is left to its default, `VIEW`), then the service's actions will
+appear in the UI both as menu items _and_ as contributions (and the service can of course be injected into other domain objects for programmatic invocation).
+
+Later on it is easy enough to refactor the code to tease apart the different responsibilities.
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_view-models.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_view-models.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_view-models.adoc
new file mode 100644
index 0000000..4e510ac
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_view-models.adoc
@@ -0,0 +1,196 @@
+[[_ugfun_domain-class-ontology_view-models]]
+= View Models
+: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/
+
+
+
+View models are similar to entities in that (unlike domain services) there can be many instances of any given type; but they differ from entities in that they are not persisted into a database.
+Instead they are recreated dynamically by serializing their state, ultimately into the URL itself.
+
+When developing an Apache Isis application you will most likely start off with the persistent domain entities:
+`Customer`, `Order`, `Product`, and so on.
+
+For some applications this may well suffice.  However, if the application
+needs to integrate with other systems, or if the application needs to support reasonably complex business processes, then you may need to look beyond just domain entities, to view models.
+This section explores these use cases.
+
+
+
+
+[[__ugfun_domain-class-ontology_view-models_externally-managed-entities]]
+== Externally-managed entities
+
+Sometimes the entities that make up your application are persisted not in the local JDO/DataNucleus database
+but reside in some other system, for example accessible only through a SOAP web service.  Logically that data
+might still be considered a domain entity and we might want to associate behaviour with it, however it cannot be
+modelled as a domain entity if only because JDO/DataNucleus doesn't know about the entity nor how to retrieve or
+update it.
+
+There are a couple of ways around this: we could either replicate the data somehow from the external system into the
+ Isis-managed database (in which case it is once again just another domain entity), or we could set up a stub/proxy for
+ the externally managed entity.  This proxy would hold the reference to the externally-managed domain entity (eg an
+ external id), as well as the "smarts" to know how to interact with that entity (by making SOAP web service calls etc).
+
+The stub/proxy is a type of view model: a view - if you like - onto the domain entity managed by the external system.
+
+[NOTE]
+====
+DataNucleus does in fact define its own link:http://www.datanucleus.org/documentation/extensions/store_manager.html[Store Manager] extension point, so an alternative architecture would be to implement this interface such that DataNucleus
+could make the calls to the external system; these externally-persisted domain entities would therefore be modelled as regular `@PersistenceCapable` entities after all.  For entities not persisted externally the implementation would delegate down to the default RDBMS-specific `StoreManager` provided by DataNucleus itself.
+
+An implementation that supported only reading from an external entity ought to be comparatively straight-forward, but
+implementing one that also supported updating external entities would need to carefully consider error conditions if the
+external system is unavailable; distributed transactions are most likely difficult/impossible to implement (and not
+desirable in any case).
+====
+
+
+[[__ugfun_domain-class-ontology_view-models_in-memory-entities]]
+== In-memory entities
+
+As a variation on the above, sometimes there are domain objects that are, conceptually at least entities, but whose
+state is not actually persisted anywhere, merely held in-memory (eg in a hash).
+
+A simple example might be read-only configuration data that is read from a config file (eg log4j appender
+definitions) but thereafter is presented in the UI just like any other entity.
+
+
+[[__ugfun_domain-class-ontology_view-models_application-layer-view-models]]
+== Application-layer view models
+
+Domain entities (whether locally persisted using JDO/DataNucleus or managed externally) are the bread-and-butter of Apache Isis applications: the focus after all, should be on the business domain concepts and ensuring that they are
+solid.  Generally those domain entities will make sense to the business domain experts: they form the _ubiquitous language_ of the domain.  These domain entities are part of the domain layer.
+
+That said, it may not always be practical to expect end-users of the application to interact solely with those domain
+entities.  For example, it may be useful to show a dashboard of the most significant data in the system to a user,
+often pulling in and aggregating information from multiple points of the app.  Obtaining this information by hand (by
+ querying the respective services/repositories) would be tedious and slow; far better to have a dashboard do the job for
+ the end user.
+
+A dashboard object is a model of the most relevant state to the end-user, in other words it is (quite literally) a view
+ model.  It is not a persisted entity, instead it belongs to the application layer.
+
+A view model need not merely aggregate data; it could also provide actions of its own.  Most likely these actions will
+be queries and will always ultimately just delegate down to the appropriate domain-layer service/repository.  But in
+some cases such view model actions might also modify state of underlying domain entities.
+
+Another common use for view models is to help co-ordinate complex business processes; for example to perform a
+quarterly invoicing run, or to upload annual interest rates from an Excel spreadsheet.  In these cases the view model
+might have some state of its own, but in most cases that state does not need to be persisted per se.
+
+.Desire Lines
+****
+One way to think of application view models is as modelling the "desire line": the commonly-trod path
+that end-users must follow to get from point A to point B as quickly as possible.
+
+To explain: there are link:http://ask.metafilter.com/62599/Where-the-sidewalk-ends[documented]
+link:https://sivers.org/walkways[examples]
+link:http://www.softpanorama.org/People/Wall/larry_wall_articles_and_interviews.shtml[that] architects of university
+campus will only add in paths some while after the campus buildings are complete: let the pedestrians figure out the
+routes they want to take.  The name we like best for this idea is "desire lines", though it has also been called
+a "desire path", "paving the path" or "paving the sidewalk".
+
+What that means is you should add view models _after_ having built up the domain layer, rather than before.  These view
+models pave that commonly-trod path, automating the steps that the end-user would otherwise have to do by hand.
+
+It takes a little practice though, because even when building the domain layer "first", you should still bear in mind
+what the use cases are that those domain entities are trying to support.  You certainly _shouldn't_ try to build out a
+domain layer that could support every conceivable use case before starting to think about view models.
+
+Instead, you should iterate.  Identify the use case/story/end-user objective that you will deliver value to the
+business.  Then build out the minimum domain entities to support that use case (refining the xref:../ugfun/ugfun.adoc#__ugfun_core-concepts_philosophy_domain-driven-design_ubiquitous-language[ubiquitous language] as you
+go).  Then, identify if there any view models that could be introduced which would simplify the end-user interactions
+with the system (perhaps automating several related use cases together).
+****
+
+[[__ugfun_domain-class-ontology_view-models_dtos]]
+== DTOs
+
+DTOs (data transfer objects) are simple classes that (according to link:https://en.wikipedia.org/wiki/Data_transfer_object[wikipedia]) "carry data between processes".
+
+If those two processes are parts of the same overall application (the same team builds and deploys both server and
+client) then there's generally no need to define a DTO; just access the entities using Apache Isis'
+xref:../ugvro/ugvro.adoc#[RestfulObjects viewer].
+
+On the other hand, if the client consuming the DTO is a different application -- by which we mean developed/deployed by
+a different (possible third-party) team -- then the DTOs act as a formal contract between the provider and the consumer.
+In such cases, exposing domain entities over xref:../ugvro/ugvro.adoc#[RestfulObjects] would be
+"A Bad Thing"(TM) because the consumer would in effect have access to implementation details that could then not be
+easily changed by the producer.
+
+To support this use case, a view model can be defined such that it can act as a DTO.  This is done by annotating the
+class using JAXB annotations; this allows the consumer to obtain the DTO in XML format along with a corresponding
+XSD schema describing the structure of that XML.  A discussion of how that might be done using an ESB such as
+link:http://camel.apache.org[Apache Camel(TM)] follows xref:../ugbtb/ugbtb.adoc#__ugfun_domain-class-ontology_view-models_dtos_consumers[below].
+
+In case it's not obvious, these DTOs are still usable as "regular" view models; they will render in the xref:../ugvw/ugvw.adoc#[Wicket viewer] just like any other.  In fact (as the xref:../ugbtb/ugbtb.adoc#_ugbtb_view-models_programming-model[programming model] section below makes clear), these JAXB-annotated view models are in many regards the most powerful of all the alternative ways of writing view models.
+
+
+It's also worth noting that it is also possible to download the XML (or XSD) straight from the UI, useful during development.
+The view model simply needs to implement the xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins_Dto[`Dto`] marker interface; the
+framework has xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins_Dto[mixins] that contribute the download actions to the view model.
+
+
+[[__ugfun_domain-class-ontology_view-models_dtos_consumers]]
+=== DTO Consumers
+
+The actual consumers of DTOs will generally obtain the XML of the view models either by requesting the XML directly,
+eg using the xref:../ugvro/ugvro.adoc#[RestfulObjects viewer], or may have the XML sent to them asynchronously using an ESB
+such as Apache Camel.
+
+In the former case, the consumer requests the DTO by calling the REST API with the appropriate HTTP `Accept` header.
+An appropriate implementation of xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`] can then be
+used to return the appropriate DTO (as XML).
+
+For the latter case, one design is simply for the application to instantiate the view model, then call the
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_JaxbService[`JaxbService`] to obtain its corresponding XML.  This can then be published onto
+the ESB, for example using an http://activemq.apache.org[Apache ActiveMQ (TM)] queue.
+
+However, rather than try to push all the data that might be needed by any of these external systems in a single XML event
+ (which would require anticipating all the requirements, likely a hopeless task), a better design is to publish only
+ the fact that something of note has changed - ie, that an action on a domain object has been invoked - and then let the consumers call back to obtain other information if required.  This can once again be done by calling the REST API with
+ an appropriate HTTP `Accept` header.
+
+[TIP]
+====
+This is an example of the link:https://leanpub.com/camel-design-patterns[VETRO pattern] (validate, enrich, transform, route, operate).  In our case we focus on the validation (to determine the nature of the inbound message, ie which action was
+invoked), and the enrich (callback to obtain a DTO with additional information required by the consumer).
+====
+
+The (non-ASF) http://github.com/isisaddons/isis-module-publishmq[Isis addons' publishmq] module provides an out-of-the-box solution of this design.  It provides an implementation of the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`],
+but which simply publishes instances of xref:../rgcms/rgcms.adoc#_rgcms_schema-aim[`ActionInvocationMemento`] to an ActiveMQ
+queue.  Camel (or similar) can then be hooked up to consume these events from this queue, and use a processor to
+parse the action memento to determine what has changed on the source system.  Thereafter, a subsequent Camel processor
+can then call back to the source - via the xref:../ugvro/ugvro.adoc[Restful Objects viewer] - to enrich the message with
+additional details using a DTO.
+
+
+
+
+
+[[__ugfun_domain-class-ontology_view-models_typical-implementation]]
+== Typical Implementation
+
+Apache Isis offers several ways to implement view models, but the most flexible/powerful is to annotate the class using JAXB annotations.
+For example:
+
+[source,java]
+----
+@XmlRootElement(name = "invoiceRun")    // <1>
+@XmlType(
+        propOrder = {                   // <2>
+            ...
+        }
+)
+public class InvoiceRun {
+    ...
+}
+----
+<1> The JAXB `@XmlRootElement` annotation indicates this is a view model to Apache Isis, which then uses JAXB to serialize the state of the view model between interactions
+<2> All properties of the view model must be listed using the `XmlType#propOrder` attribute.
+
+Use JAXB elements such as `@XmlElement` for properties and the combination of `@XmlElementWrapper` and `@XmlElement` for collections.
+Properties can be ignored (for serialization) using `@XmlTransient`.
+

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_drop-downs-and-defaults.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_drop-downs-and-defaults.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_drop-downs-and-defaults.adoc
new file mode 100644
index 0000000..fdf2a1f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_drop-downs-and-defaults.adoc
@@ -0,0 +1,65 @@
+[[_ugfun_drop-downs-and-defaults]]
+= Drop Downs and Defaults
+: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/
+
+NOTE: FIXME
+
+
+== For Properties
+
+NOTE: FIXME
+
+### Choices for Property
+
+NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`]
+
+### Auto-complete for property
+
+NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`]
+
+### Default for property
+
+NOTE: FIXME -  xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_default[`default...()`]
+
+
+
+
+== For Action Parameters
+
+NOTE: FIXME
+
+### Choices for action parameter
+
+NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`]
+
+### Dependent choices for action params
+
+NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`]
+
+### Auto-complete for action param
+
+NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`]
+
+### Default for action param
+
+NOTE: FIXME -  xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_default[`default...()`]
+
+
+
+
+
+== For both Properties and Action Parameters
+
+NOTE: FIXME
+
+
+### Drop-down for limited number of instances
+
+NOTE: FIXME - xref:../rgant/rgant.adoc#_rgant-DomainObject_bounded[`@DomainObject#bounded()`]
+
+
+### Auto-complete (repository-based)
+
+xref:../rgant/rgant.adoc#_rgant-DomainObject_autoCompleteRepository[`@DomainObject#autoCompleteRepository()`]

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos.adoc
deleted file mode 100644
index 3d2af8e..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos.adoc
+++ /dev/null
@@ -1,20 +0,0 @@
-[[_ugfun_how-tos]]
-= How tos
-: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/
-
-
-This chapter provides a grab bag of "how-to"s and tips to help you go about actually developing Apache Isis domain applications.
-
-include::_ugfun_how-tos_class-structure.adoc[leveloffset=+1]
-include::_ugfun_how-tos_ui-hints.adoc[leveloffset=+1]
-include::_ugfun_how-tos_domain-services.adoc[leveloffset=+1]
-include::_ugfun_how-tos_crud.adoc[leveloffset=+1]
-include::_ugfun_how-tos_business-rules.adoc[leveloffset=+1]
-include::_ugfun_how-tos_derived-members.adoc[leveloffset=+1]
-include::_ugfun_how-tos_drop-downs-and-defaults.adoc[leveloffset=+1]
-include::_ugfun_how-tos_bulk-actions.adoc[leveloffset=+1]
-include::_ugfun_how-tos_simulating-collections-of-values.adoc[leveloffset=+1]
-include::_ugfun_how-tos_render-all-properties-in-tables.adoc[leveloffset=+1]
-

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_bulk-actions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_bulk-actions.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_bulk-actions.adoc
deleted file mode 100644
index f3d5e41..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_bulk-actions.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-[[_ugfun_how-tos_bulk-actions]]
-= Bulk Actions
-: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/
-
-NOTE: FIXME - xref:../rgant/rgant.adoc#_rgant-Action_invokeOn[`@Action#invokeOn()`]
-

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_business-rules.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_business-rules.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_business-rules.adoc
deleted file mode 100644
index 8c02ad3..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_business-rules.adoc
+++ /dev/null
@@ -1,72 +0,0 @@
-[[_ugfun_how-tos_business-rules]]
-= Business Rules
-: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/
-
-NOTE: FIXME
-
-
-
-== Visibility ("see it")
-
-NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_hide[`hide...()`]
-
-### Hide a Property
-
-### Hide a Collection
-
-### Hide an Action
-
-### Hide a Contributed Property, Collection or Action
-
-### All Members Hidden
-
-
-
-
-== Usability ("use it")
-
-NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_disable[`disable...()`]
-
-### Disable a Property
-
-### Disable a Collection
-
-### Disable an Action
-
-### Disable a Contributed Property, Collection or Action
-
-### All Members Unmodifiable (Disabling the Edit Button)
-
-Sometimes an object is unmodifiable.
-
-In the Wicket viewer this means disabling the edit button.
-
-#### Declarative
-
-`@DomainObject(editing=...)`
-
-#### Imperative
-
-
-
-== Validity ("do it")
-
-NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_validate[`validate...()`], xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_validateAddTo[`validateAddTo...()`], xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_validateRemoveFrom[`validateRemoveFrom...()`] and xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_validate[`validate()`]
-
-
-### Validate (change to) a Property
-
-### Validate (adding or removing from) a Collection
-
-### Validate (arguments to invoke) an Action
-
-### Validating a Contributed Property, Collection or Action
-
-### Declarative validation
-
-NOTE: FIXME - using xref:../rgant/rgant.adoc#_rgant-Parameter_mustSatisfy[`@Parameter#mustSatisfy()`], xref:../rgant/rgant.adoc#_rgant-Property_mustSatisfy[`@Property#mustSatisfy()`]
-
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure.adoc
deleted file mode 100644
index 4e0b7f9..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure.adoc
+++ /dev/null
@@ -1,41 +0,0 @@
-[[_ugfun_how-tos_class-structure]]
-= Class Structure
-: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 works by building a metamodel of the domain objects: entities, xref:../ugbtb/ugbtb.adoc#_ugbtb_view-models[view model]s and services.
-The class methods of both entities and view models represent both state -- (single-valued) properties and (multi-valued) collections -- and behaviour -- actions.  The class members of domain services is simpler: just behaviour, ie actions.
-
-In the automatically generated UI a property is rendered as a field.
-This can be either of a value type (a string, number, date, boolean etc) or can be a reference to another entity.
-A collection is generally rendered as a table.
-
-In order for Apache Isis to build its metamodel the domain objects must follow some conventions: what we call the _Apache Isis Programming Model_.
-This is just an extension of the pojo / JavaBean standard of yesteryear: properties and collections are getters/setters, while actions are simply any remaining `public` methods.
-
-Additional metamodel semantics are inferred both imperatively from _supporting methods_ and declaratively from annotations.
-
-In this section we discuss the mechanics of writing domain objects that comply with Apache Isis' programming model.
-
-[TIP]
-====
-In fact, the Apache Isis programming model is extensible; you can teach Apache Isis new programming conventions and you can remove existing ones; ultimately they amount to syntax.
-The only real fundamental that can't be changed is the notion that objects consist of properties, collections and actions.
-
-You can learn more about extending Apache Isis programming model xref:../ugbtb/ugbtb.adoc#_ugbtb_programming-model[here].
-====
-
-
-include::_ugfun_how-tos_class-structure_class-definition.adoc[leveloffset=+1]
-include::_ugfun_how-tos_class-structure_properties.adoc[leveloffset=+1]
-include::_ugfun_how-tos_class-structure_collections.adoc[leveloffset=+1]
-include::_ugfun_how-tos_class-structure_actions.adoc[leveloffset=+1]
-include::_ugfun_how-tos_class-structure_inject-services.adoc[leveloffset=+1]
-
-include::_ugfun_how-tos_class-structure_properties-vs-parameters.adoc[leveloffset=+1]
-
-
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_actions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_actions.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_actions.adoc
deleted file mode 100644
index 1954d64..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_actions.adoc
+++ /dev/null
@@ -1,264 +0,0 @@
-[[_ugfun_how-tos_class-structure_actions]]
-= Actions
-: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/
-
-
-
-While xref:../ugfun/ugfun.adoc#_ugfun_how-tos_class-structure_properties[properties] and xref:../ugfun/ugfun.adoc#_ugfun_how-tos_class-structure_collections[collections] define the state held by a domain object (its "know what" responsibilities), actions define the object's behaviour (its "know how-to" responsibilities).
-
-An application whose domain objects have only/mostly "know-what" responsibilities is pretty dumb: it requires that the end-user know the business rules and doesn't modify the state of the domain objects such that they are invalid (for example, an "end date" being before a "start date").
-Such applications are often called CRUD applications (create/read/update/delete).
-
-In more complex domains, it's not realistic/feasible to expect the end-user to have to remember all the different business rules that govern the valid states for each domain object.
-So instead actions allow those business rules to be encoded programmatically.
-An Apache Isis application doesn't try to constrain the end-user as to way in which they interact with the user (it doesn't attempt to define a rigid business process) but it does aim to ensure that business rule invariants are maintained, that is that business objects aren't allowed to go into an invalid state.
-
-For simple domain applications, you may want to start prototyping only with properties, and only later introduce actions (representing the most common business operations).
-But an alternative approach, recommended for more complex applications, is actually to start the application with all properties non-editable.
-Then, as the end-user requires the ability to modify some state, there is a context in which to ask the question "why does this state need to change?" and "are their any side-effects?" (ie, other state that changes at the same time, or other behaviour that should occur).
-If the state change is simple, for example just being able to correct an invalid address, or adding a note or comment, then that can probably be modelled as a simple editable property.
-But if the state change is more complex, then most likely an action should be used instead.
-
-
-[[__ugfun_how-tos_class-structure_actions_defining-actions]]
-== Defining actions
-
-Broadly speaking, actions are all the `public` methods that are not getters or setters which represent properties or collections.
-This is a slight simplification; there are a number of other method prefixes (such as `hide` or `validate`) that represent xref:../ugfun/ugfun.adoc#_ugfun_how-tos_business-rules[business rules]); these also not treated as actions.
-And, any method that are annotated with `@Programmatic` will also be excluded.
-But by and large, all other methods such as `placeOrder(...)` or `approveInvoice(...)` will be treated as actions.
-
-For example:
-
-[source,java]
-----
-@Action(semantics=SemanticsOf.IDEMPOTENT)       // <1>
-public ShoppingBasket addToBasket(
-        Product product,
-        @ParameterLayout(named="Quantity")      // <2>
-        int quantity
-        ) {
-    ...
-    return this;
-}
-----
-<1> `@Action` annotation is optional but used to specify additional domain semantics (such as being idempotent).
-<2> The names of action parameters (as rendered in the UI) will by default be the parameter types, not the paramter names.
-For the `product` parameter this is reasonable, but not so for the `quantity` parameter (which would by default show up with a name of "int".
-The `@ParameterLayout` annotation provides a UI hint to the framework.
-
-[TIP]
-====
-The (non-ASF) Isis addons' http://github.com/isisaddons/isis-metamodel-paraname8[paraname8] metamodel extension allows the parameter name to be used in the UI, rather than the type.
-====
-
-
-[[__ugfun_how-tos_class-structure_actions_reference-parameter-types]]
-== (Reference) Parameter types
-
-Parameter types can be value types or reference types.
-In the case of primitive types, the end-user can just enter the value directly through the parameter field.
-In the case of reference types however (such as `Product`), a drop-down must be provided from which the end-user to select.
-This is done using either a supporting xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_choices[`choices`] or xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete`] method.
-The "choices" is used when there is a limited set of options, while "autoComplete" is used when there are large set of options such that the end-user must provide some characters to use for a search.
-
-For example, the `addToBasket(...)` action shown above might well have a :
-
-[source,java]
-----
-@Action(semantics=SemanticsOf.IDEMPOTENT)
-public ShoppingBasket addToBasket(
-        Product product,
-        @ParameterLayout(named="Quantity")
-        int quantity
-        ) {
-    ...
-    return this;
-}
-public List<Product> autoComplete0AddToBasket(              // <1>
-    @MinLength(3)                                           // <2>
-    String searchTerm) {
-    return productRepository.find(searchTerm);              // <3>
-}
-@javax.inject.Inject
-ProductRepository productRepository;
-----
-<1> Supporting `autoComplete` method.
-The "0" in the name means that this corresponds to parameter 0 of the "addToBasket" action (ie `Product`).
-It is also required to return a Collection of that type.
-<2> The xref:../rgant/rgant.adoc#_rgant_MinLength[`@MinLength`] annotation defines how many characters the end-user must enter before performing a search.
-<3> The implementation delegates to an injected repository service.  This is typical.
-
-Note that it is also valid to define "choices" and "autoComplete" for value types (such as `quantity`, above); it just isn't as common to do so.
-
-[[__ugfun_how-tos_class-structure_actions_reference-parameter-types_removing-boilerplate]]
-=== Removing boilerplate
-
-To save having to define an `autoCompleteNXxx(...)` method everywhere that a reference to a particular type (such as `Product`) appears as an action parameter, it is also possible to use the `@DomainObject` annotation on `Product` itself:
-
-[source,java]
-----
-@DomainObject(
-    autoCompleteRepository=ProductRepository.class          // <1>
-    autoCompleteAction="find"                               // <2>
-)
-public class Product ... {
-    ...
-}
-----
-<1> Whenever an action parameter requiring a `Product` is defined, provide an autoComplete drop-down automatically
-<2> Use the "find" method of `ProductRepository` (rather than the default name of "autoComplete")
-
-(As noted above), if the number of available instances of the reference type is a small number (in other words, all of which could comfortably be shown in a drop-down) then instead the `choicesNXxx()` supporting method can be used.
-This too can be avoided by annotating the referenced class.
-
-For example, suppose we have an action to specify the `PaymentMethodType`, where there are only 10 or so such (Visa, Mastercard, Amex, Paypal etc).
-We could define this as:
-
-[source,java]
-----
-public Order payUsing(PaymentMethodType type) {
-    ...
-}
-----
-
-where `PaymentMethodType` would be annotated using:
-
-[source,java]
-----
-@DomainObject(
-    bounded=true                            // <1>
-)
-public class PaymentMethodType ... {
-    ...
-}
-----
-<1> only a small (ie "bounded") number of instances available, meaning that the framework should render all in a drop-down.
-
-
-[[__ugfun_how-tos_class-structure_actions_collection-parameter-types]]
-== Collection Parameter types
-
-Action parameters can also be collections of values (for example `List<String>`), or can be collections of references (such as `List<Customer>`).
-
-For example:
-
-[source,java]
-----
-@Action(semantics=SemanticsOf.IDEMPOTENT)
-public ShoppingBasket addToBasket(
-        List<Product> products,
-        @ParameterLayout(named="Quantity") int quantity
-        ) {
-    ...
-    return this;
-}
-public List<Product> autoComplete0AddToBasket(@MinLength(3) String searchTerm) {
-    return ...
-}
-----
-
-As the example suggests, any collection parameter type must provide a way to select items, either by way of a "choices" or "autoComplete" supporting method or alternatively defined globally using xref:../rgant/rgant.adoc#_rgant_DomainObject[`@DomainObject`] on the referenced type (described xref:../ugfun/ugfun.adoc#__ugfun_how-tos_class-structure_actions_reference-parameter-types_removing-boilerplate[above]).
-
-
-[[__ugfun_how-tos_class-structure_actions_optional-parameters]]
-== Optional Parameters
-
-Whereas the xref:../ugfun/ugfun.adoc#__ugfun_how-tos_class-structure_properties_optional-properties[optionality of properties] is defined using xref:../rgant/rgant.adoc#_rgant_Column_allowsNull[`@javax.jdo.annotations.Column#allowsNull()`], that JDO annotation cannot be applied to parameter types.
-Instead, either the xref:../rgant/rgant.adoc#_rgant_Nullable[`@Nullable`] annotation or the xref:../rgant/rgant.adoc#_rgant_Parameter_optionality[`@Parameter#optionality()`]  annotation/attribute is used.
-
-For example:
-
-[source,java]
-----
-@javax.jdo.annotations.Column(allowsNull="true")                // <1>
-@lombok.Getter @lombok.Setter
-private LocalDate shipBy;
-
-public Order invoice(
-                PaymentMethodType paymentMethodType,
-                @Nullable                                       // <2>
-                @ParameterLayout(named="Ship no later than")
-                LocalDate shipBy) {
-    ...
-    setShipBy(shipBy)
-    return this;
-}
-----
-<1> Specifies the property is optional.
-<2> Specifies the corresponding parameter is optional.
-
-See also xref:../ugfun/ugfun.adoc#_ugfun_how-tos_class-structure_properties-vs-parameters[properties vs parameters].
-
-[[__ugfun_how-tos_class-structure_actions_string-parameters]]
-== ``String`` Parameters (Length)
-
-Whereas the xref:../ugfun/ugfun.adoc#__ugfun_how-tos_class-structure_properties_mapping-strings[length of string properties] is defined using xref:../rgant/rgant.adoc#_rgant_Column_length[`@javax.jdo.annotations.Column#length()`], that JDO annotation cannot be applied to parameter types.
-Instead, the xref:../rgant/rgant.adoc#_rgant_Parameter_maxLength[`@Parameter#maxLength()`] annotation/attribute is used.
-
-For example:
-
-[source,java]
-----
-@javax.jdo.annotations.Column(length=50)                // <1>
-@lombok.Getter @lombok.Setter
-private String firstName;
-
-@javax.jdo.annotations.Column(length=50)
-@lombok.Getter @lombok.Setter
-private String lastName;
-
-public Customer updateName(
-                @Parameter(maxLength=50)                // <2>
-                @ParameterLayout(named="First name")
-                String firstName,
-                @Parameter(maxLength=50)
-                @ParameterLayout(named="Last name")
-                String lastName) {
-    setFirstName(firstName);
-    setLastName(lastName);
-    return this;
-}
-----
-<1> Specifies the property length using the JDO xref:../rgant/rgant.adoc#_rgant_Column_length[`@Column#length()`] annotation
-<2> Specifies the parameter length using the (Apache Isis) xref:../rgant/rgant.adoc#_rgant_Parameter_maxLength[`@Parameter#maxLength()`] annotation
-
-[IMPORTANT]
-====
-Incidentally, note in the above example that the new value is assigned to the properties using the setter methods; the action does not simply set the instance field directly.
-This is important, because it allows JDO/DataNucleus to keep track that this instance variable is "dirty" and so needs flushing to the database table before the transaction completes.
-====
-
-See also xref:../ugfun/ugfun.adoc#_ugfun_how-tos_class-structure_properties-vs-parameters[properties vs parameters].
-
-[[__ugfun_how-tos_class-structure_actions_bigdecimal-parameters]]
-== ``BigDecimal``s (Precision)
-
-Whereas the xref:../ugfun/ugfun.adoc#__ugfun_how-tos_class-structure_properties_mapping-bigdecimals[precision of BigDecimal properties] is defined using xref:../rgant/rgant.adoc#_rgant_Column_scale[`@javax.jdo.annotations.Column#scale()`], that JDO annotation cannot be applied to parameter types.
-Instead, the xref:../rgant/rgant.adoc#_rgant_Digits_fraction[`@javax.validation.constraints.Digits#fraction()`] annotation/attribute is used.
-
-For example:
-
-[source,java]
-----
-@javax.jdo.annotations.Column(scale=2)                              // <1>
-@lombok.Getter @lombok.Setter
-private BigDecimal discountRate;
-
-public Order updateDiscount(
-                @javax.validation.constraints.Digits(fraction=2)    // <2>
-                @ParameterLayout(named="Discount rate")
-                String discountRate) {
-    setDiscountRate(discountRate);
-    return this;
-}
-----
-<1> Specifies the property precision using xref:../rgant/rgant.adoc#_rgant_Column_scale[`@Column#scale()`]
-<2> Specifies the corresponding parameter precision using xref:../rgant/rgant.adoc#_rgant_Digits_fraction[`@Digits#fraction()`].
-
-See also xref:../ugfun/ugfun.adoc#_ugfun_how-tos_class-structure_properties-vs-parameters[properties vs parameters].
-
-
-

[24/58] [abbrv] isis git commit: ISIS-1521: working on ugfun.adoc

[da...@apache.org]

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_object-members.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_object-members.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_object-members.adoc
new file mode 100644
index 0000000..38a18c7
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_object-members.adoc
@@ -0,0 +1,87 @@
+[[_ugfun_building-blocks_objects-members]]
+= Object Members
+: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/
+
+
+Every domain object in Apache Isis consists of (at most) three types of members:
+
+* properties, such as a ``Customer``'s `firstName`
+
+* collections, such as a ``Customer``'s `orders` collection of ``Order``s
+
+* actions, such as a ``Customer'``s `placeOrder(...)` method.
+
+Some domain objects -- specifically domain services and mixins -- only have actions.
+In the case of contributing services and mixins these actions can (depending upon their semantics and signatures) be represented as derived properties or collections on the entity/view model to which they contribute/mix-in.
+
+
+== Properties
+
+Properties follow the standard getter/setter pattern, with the return type being a scalar (a value object or another entity or view model).
+
+For example, with:
+
+[source,java]
+----
+public class Customer
+    private String firstName;
+    public String getFirstName() { return firstName; }
+    public void setFirstName(String firstName) { this.firstName = firstName; }
+    ...
+}
+----
+
+the framework infers the `Customer` domain entity, which in turn has a `firstName` string _property_.
+
+
+== Collections
+
+Collections are also represented by a getter and setter, however the return type is a `Collection` or subtype.
+
+For example, with:
+
+[source,java]
+----
+public class Customer
+    private SortedSet<Order> orders = new TreeSet<Order>();
+    public SortedSet<Order> getOrders() { return orders; }
+    public void setOrders(SortedSet<Order> orders) { this.orders = orders; }
+    ...
+}
+----
+
+the framework infers the `orders` _collection_.
+
+[TIP]
+====
+The most commonly used collection type is `java.util.SortedSet`; entities are most commonly mapped to a relational database (ie a datastore with set semantics) and we recommend that all entities define a natural ordering so that when rendered in the UI they will be ordered "meaningfully" to the end-user.
+====
+
+
+== Actions
+
+The third type of object member is actions.
+(To a first approximation), actions are all public methods that do not represent properties or collections.
+
+For example:
+
+[source,java]
+----
+public class Customer
+    public Customer placeOrder(Product p, int quantity) { ... }
+    ...
+}
+----
+
+corresponds to the `placeOrder` _action_.
+
+[NOTE]
+====
+The above _is_ a simplification; the Apache Isis programming model also recognizes a number of other supporting methods each of which has its own prefix such as `hide`, `disable` or `validate`.
+These can be considered as "reserved words" in Apache Isis, and do _not_ correspond to actions even though they have public visibility.
+====
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_types-of-domain-objects.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_types-of-domain-objects.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_types-of-domain-objects.adoc
new file mode 100644
index 0000000..87f28b8
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_types-of-domain-objects.adoc
@@ -0,0 +1,35 @@
+[[_ugfun_building-blocks_types-of-domain-objects]]
+= Type of Domain Objects
+: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 supports recognises four main types of domain classes:
+
+* *domain entities* - domain objects persisted to the database using JDO/DataNucleus; for example `Customer`
+
+* *domain services* - generally singletons, automatically injected, and providing various functionality; for example `CustomerRepository`
+
+* *view models* - domain objects that are a projection of some state held by the database, in support a particular use case; for example `CustomerDashboard` (to pull together commonly accessed information about a customer).
+
+* *mixins* - allow functionality to be "contributed" in the UI by one module to another object, similar to traits or extension methods provided in some programming languages.
+This is an important capability to help keep large applications xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling[decoupled].
+
+From the end-user's perspective the UI displays a single domain object instance that has state (that is, a domain entity or a view model) per page.
+The end-user can then inspect and modify its state, and navigate to related objects.
+
+Domain classes are generally recognized using annotations.
+Apache Isis defines its own set of annotations, while entities are annotated using JDO/DataNucleus (though XML can also be used if required).
+Apache Isis recognizes some of the JDO and JAXB annotations and infers domain semantics from these annotations.
+Similarly, JAXB annotations are typically used for view models.
+There is a smattering of other Java/JEE annotations that are also supported, such as `@javax.inject.Inject` and `@javax.annotation.Nullable`.
+
+The following subsections explain this in further detail.
+
+
+include::_ugfun_building-blocks_types-of-domain-objects_domain-entities.adoc[leveloffset=+1]
+include::_ugfun_building-blocks_types-of-domain-objects_domain-services.adoc[leveloffset=+1]
+include::_ugfun_building-blocks_types-of-domain-objects_view-models.adoc[leveloffset=+1]
+include::_ugfun_building-blocks_types-of-domain-objects_mixins.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_types-of-domain-objects_domain-entities.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_types-of-domain-objects_domain-entities.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_types-of-domain-objects_domain-entities.adoc
new file mode 100644
index 0000000..e2bb0a7
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_types-of-domain-objects_domain-entities.adoc
@@ -0,0 +1,37 @@
+[[_ugfun_building-blocks_types-of-domain-objects_domain-entities]]
+= Domain Entities
+: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/
+
+
+Most domain objects that the end-user interacts with are _domain entities_, such as `Customer`, `Order`, `Product` and so on.
+These are persistent objects and which are mapped to a database (usually relational), using JDO/DataNucleus annotations.
+
+Some domain entities are really aggregates, a combination of multiple objects.
+A commonly cited example of this is an `Order`, which really consists of both a root `Order` entity and a collection of ``OrderItem``s.
+From the end-users' perspective, when they talk of "order" they almost always mean the aggregate rather than just the `Order` root entity.
+
+Eric Evans' link:http://books.google.com/books/about/Domain_Driven_Design.html?id=hHBf4YxMnWMC[Domain Driven Design] has a lot to say about aggregate roots and their responsibilities: in particular that it is the responsibility of the aggregate root to maintain the invariants of its component pieces, and that roots may only reference other roots.
+There's good logic here: requiring only root-to-root relationships reduces the number of moving parts that the developer has to think about.
+
+On the other hand, this constraint can substantially complicate matters when mapping domain layer to the persistenec layer.
+DDD tends to de-emphasise such matters: it aims to be completely agnostic about the persistence layer, with the responsibilities for managing relationships moved (pretty much by definition) into the domain layer.
+
+As a framework though Apache Isis is less dogmatic about such things.
+Generally the domain objects are mapped to a relational database and so we can lean on the referential integrity capabilities of the persistence layer to maintain referential invariants.
+Said another way: we don't tend to require that only roots can maintain roots: we don't see anything wrong in an `InvoiceItem` referencing an `OrderItem`, for example.
+
+Nonetheless the concepts of "aggregate" and "aggregate root" are worth holding onto.
+You'll likely find that you'll define a repository service (discussed in more detail below) for each aggregate root: for example `Order` will have a corresponding `OrderRepository` service.
+Similarly, you may also have a factory service, for example `OrderFactory`.
+However, you are less likely to have a repository service for the parts of an aggregate root: the role of retrieving ``OrderItem``s should fall to the `Order` (typically by way of lazy loading of an "items" collection) rather than through an `OrderItemRepository` service.
+Again, this isn't a hard-n-fast rule, but a good rule of thumb.
+
+
+[TIP]
+====
+Details on how to actually write a domain entity (the programming model for domain entities) is
+xref:../ugfun/ugfun.adoc#_ugfun_programming-model_domain-entities[here].
+====
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_types-of-domain-objects_domain-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_types-of-domain-objects_domain-services.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_types-of-domain-objects_domain-services.adoc
new file mode 100644
index 0000000..726c004
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_types-of-domain-objects_domain-services.adoc
@@ -0,0 +1,66 @@
+[[_ugfun_building-blocks_types-of-domain-objects_domain-services]]
+= Domain Services
+: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/
+
+
+_Domain services_ are (usually) singleton stateless services that provide additional functionality.
+Domain services consist of a set of logically grouped actions, and as such follow the same conventions as for entities.
+However, a service cannot have (persisted) properties, nor can it have (persisted) collections.
+
+A very common type of domain service is a repository, that is used to look up existing instances of a domain entity.
+For example, for the `Customer` entity there may be a `CustomerRepository`, while for `Order` entity there may be an `OrderRepository`.
+
+Similarly, entities might also have a corresponding factory service: a `CustomerFactory` or an `OrderFactory`; Evans' link:http://books.google.com/books/about/Domain_Driven_Design.html?id=hHBf4YxMnWMC[Domain Driven Design], draws a clear distinction is made between a factory (that creates object) and a repository (that is used to find existing objects).
+
+On the other hand, from an end-users' perspective the act of finding an existing object vs creating a new one are quite closely related.
+For this reason, in Apache Isis it's therefore quite common to have a single domain service that acts as both a factory and a repository (and is usually called just a "repository").
+
+The behaviour of these services is rendered in various ways, though the most obvious is as the menu actions on the top-level menu bars in the xref:../ugvw/ugvw.adoc#[Wicket viewer]'s UI.
+
+Domain services can also be used for a number of other purposes:
+
+* to provide additional non-UI functionality; an example being to perform an address geocoding lookup against the google-maps API, or to perform some calculation, or attach a barcode, send an email etc
+
+* to act as a subscribers to the event bus, potentially influencing events fired by some other module (a key technique for decoupling large applications) +
++
+This is discussed in more detail below, in the section on xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_events[events].
+
+* to implement an link:https://en.wikipedia.org/wiki/Service_provider_interface[SPI] of the Apache Isis framework, most notably cross-cutting concerns such as security, command profiling, auditing and publishing.
+
+* to contribute behaviour or (derived) state to entities/view models. +
++
+
+[NOTE]
+====
+Mixins can do everything that contributed services can, and have a cleaner programming model.
+As such, contributed services should be considered a deprecated feature; it may be removed in a future release.
+====
+
+Domain objects of any type (entities, other services, view models, mixins) can also delegate to domain services; domain services are automatically injected into every other domain object.
+This injection of domain services into entities is significant: it allows business logic to be implemented in the domain entities, rather than have it "leach away" into
+supporting service layers.
+Said another way: it is the means by which Apache Isis helps you avoid the anaemic domain model anti-pattern.
+
+Domain services are instantiated once and once only by the framework, and are used to centralize any domain logic that does not logically belong in a domain entity or value.
+
+[TIP]
+====
+Details on how to actually write a domain service (the programming model for domain services) is
+xref:../ugfun/ugfun.adoc#_ugfun_programming-model_domain-services[here].
+====
+
+
+== Hexagonal Arch. + services
+
+It's worth extending the xref:../ugfun/ugfun.adoc#_ugfun_core-concepts_philosophy_hexagonal-architecture[Hexagonal Architecture] to show where domain services fit in:
+
+.The hexagonal architecture with Isis addons
+image::{_imagesdir}core-concepts/philosophy/hexagonal-architecture-addons.png[width="700px"]
+
+The (non-ASF) link:http://isisaddons.org[Isis Addons] provide SPI implementations of the common cross-cutting concerns.
+They also provide a number of APIs for domain objects to invoke (not shown in the diagram).
+You can also write your own domain services as well, for example to interface with some external CMS system, say.
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_types-of-domain-objects_mixins.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_types-of-domain-objects_mixins.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_types-of-domain-objects_mixins.adoc
new file mode 100644
index 0000000..a663702
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_types-of-domain-objects_mixins.adoc
@@ -0,0 +1,56 @@
+[[_ugfun_building-blocks_types-of-domain-objects_mixins]]
+= Mixins
+: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/
+
+
+The final type of domain object is the *mixin*.
+These are similar to traits or extension methods in other programming languages, in that they contribute (or rather, mixin) both behaviour or (derived) state to entities/view models.
+
+A mixin object allows one class to contribute behaviour - actions, (derived) properties and (derived) collections - to another domain object, either a domain entity or view model.
+
+The allows the app to stay decoupled, so that it doesn't degrade into the proverbial link:http://www.laputan.org/mud/mud.html#BigBallOfMud["big ball of mud"].
+Mixins allow dependencies to be inverted, so that the dependencies between modules can be kept acyclic and under control.
+
+For example, the contributee (eg `Customer`, being mixed into) is in one module, while the contributor mixin (`DocumentHolder_documents`) is in some other module.
+The `customer` module knows about the `document` module, but not vice versa.
+
+Mixins are also a convenient mechanism for grouping functionality even for a concrete type, helping to rationalize about the dependency between the data and the behaviour.
+Each mixin is in effect a single behavioural "responsibility" of the domain object.
+
+
+There are also practical reasons for moving behaviour out of entities even within the same module, because structuring your application this way helps support hot-reloading of Java classes (so that you can modify and recompile your application without having to restart it).
+This can provide substantial productivity gains.
+
+The Hotspot JVM has limited support for hot reloading; generally you can change method implementations but you cannot introduce new methods.
+However, the link:https://dcevm.github.io/[DCEVM] open source project will patch the JVM to support much more complete hot reloading support.
+There are also, of course, commercial products such as JRebel.
+
+The main snag in all this is the DataNucleus enhancer... any change to entities is going to require the entity to be re-enhanced, and the JDO metamodel recreated, which invariably breaks things.
+So hot-reloading of an app whose fundamental structure is changing is likely to remain a no-no.
+
+However, chances are that the structure of your domain objects (the data) will change much less rapidly than the behaviour of those domain objects.
+Thus, it's the behaviour that you're most likely wanting to change while the app is still running.
+If you move that behaviour out into mixins, then these can be reloaded happily.
+(And when running in prototype mode), Apache Isis will automatically recreate the portion of the metamodel for any domain object as it is rendered.
+
+[TIP]
+====
+Details on how to actually write a mixin (the programming model for mixins) is
+xref:../ugfun/ugfun.adoc#_ugfun_programming-model_mixins[here].
+====
+
+
+.DCI Architecture
+****
+Mixins are an implementation of the link:http://www.artima.com/articles/dci_vision.html[DCI architecture] architecture, as formulated and described by link:https://en.wikipedia.org/wiki/Trygve_Reenskaug[Trygve Reenskaug] and link:https://en.wikipedia.org/wiki/Jim_Coplien[Jim Coplien].
+Reenskaug was the inventor of the MVC pattern (and also the external examiner for Richard Pawson's PhD thesis), while Coplien has a long history in object-orientation, C++ and patterns.
+
+DCI stands for Data-Context-Interaction and is presented as an evolution of object-oriented programming, but one where behaviour is bound to objects dynamically rather than statically in some context or other.
+The mixin pattern is Apache Isis' straightforward take on the same basic concept.
+
+You might also wish to check out link:http://zest.apache.org[Apache Zest] (formerly Qi4J), which implements a much more general purpose implementation of the same concepts.
+****
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_types-of-domain-objects_view-models.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_types-of-domain-objects_view-models.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_types-of-domain-objects_view-models.adoc
new file mode 100644
index 0000000..bc08274
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_types-of-domain-objects_view-models.adoc
@@ -0,0 +1,162 @@
+[[_ugfun_building-blocks_types-of-domain-objects_view-models]]
+= View Models
+: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/
+
+
+View models are similar to entities in that (unlike domain services) there can be many instances of any given type.
+End users interact with view models in the same way as a domain entity, indeed they are unlikely to distinguish one from the other.
+
+However, whereas a domain entities is mapped to a datastore, view models are not.
+Instead they are recreated dynamically by serializing their state, ultimately into the URL itself (meaning their state it is in effect implicitly managed by the client browser).
+You will notice that the URL for view models (as shown in xref:../ugvw/ugvw.adoc#[Wicket viewer] or xref:../ugvro/ugvro.adoc#[RestfulObjects viewer]) tends to be quite long.
+
+This capability opens up a number of more advanced use cases:
+
+* In the same way that an (RDBMS) database view can aggregate and abstract from multiple underlying database tables, so a view model sits on top of one or many underlying entities.
+
+* A view model could also be used as a proxy for some externally managed entity, accessed over a web service or REST API; it could even be a representation of state held in-memory (such as user preferences, for example).
+
+* view models can also be used to support a particular use case.
+An example that comes to mind is to expose a list of scanned PDFs to be processed as an "intray", showing the list of PDFs on one side of the page, and the current PDF being viewed on the other.
+Such view models are part of the application layer, not part of the domain layer (where entities live).
+
+We explore these use cases in more detail below.
+
+
+[TIP]
+====
+Details on how to actually write a view model (the programming model for view models) is
+xref:../ugfun/ugfun.adoc#_ugfun_programming-model_view-models[here].
+====
+
+
+
+[[__ugfun_building-blocks_view-models_externally-managed-entities]]
+== Externally-managed entities
+
+Sometimes the entities that make up your application are persisted not in the local JDO/DataNucleus database but reside in some other system, for example accessible only through a SOAP web service.
+Logically that data might still be considered a domain entity and we might want to associate behaviour with it, however it cannot be modelled as a domain entity if only because JDO/DataNucleus doesn't know about the entity nor how to retrieve or update it.
+
+There are a couple of ways around this: we could either replicate the data somehow from the external system into the Isis-managed database (in which case it is once again just another domain entity), or we could set up a stub/proxy for the externally managed entity.
+This proxy would hold the reference to the externally-managed domain entity (eg an external id), as well as the "smarts" to know how to interact with that entity (by making SOAP web service calls etc).
+
+The stub/proxy is a type of view model: a view -- if you like -- onto the domain entity managed by the external system.
+
+[NOTE]
+====
+DataNucleus does in fact define its own link:http://www.datanucleus.org/documentation/extensions/store_manager.html[Store Manager] extension point, so an alternative architecture would be to implement this interface such that DataNucleus could make the calls to the external system; these externally-persisted domain entities would therefore be modelled as regular `@PersistenceCapable` entities after all.
+For entities not persisted externally the implementation would delegate down to the default RDBMS-specific `StoreManager` provided by DataNucleus itself.
+
+An implementation that supported only reading from an external entity ought to be comparatively straight-forward, but implementing one that also supported updating external entities would need to carefully consider error conditions if the external system is unavailable; distributed transactions are most likely difficult/impossible to implement (and not desirable in any case).
+====
+
+
+[[__ugfun_building-blocks_view-models_in-memory-entities]]
+== In-memory entities
+
+As a variation on the above, sometimes there are domain objects that are, conceptually at least entities, but whose state is not actually persisted anywhere, merely held in-memory (eg in a hash).
+
+A simple example might be read-only configuration data that is read from a config file (eg log4j appender definitions) but thereafter is presented in the UI just like any other entity.
+
+
+[[__ugfun_building-blocks_view-models_application-layer-view-models]]
+== Application-layer view models
+
+Domain entities (whether locally persisted using JDO/DataNucleus or managed externally) are the bread-and-butter of Apache Isis applications: the focus after all, should be on the business domain concepts and ensuring that they are solid.
+Generally those domain entities will make sense to the business domain experts: they form the _ubiquitous language_ of the domain.  These domain entities are part of the domain layer.
+
+That said, it may not always be practical to expect end-users of the application to interact solely with those domain entities.
+For example, it may be useful to show a dashboard of the most significant data in the system to a user, often pulling in and aggregating information from multiple points of the app.
+Obtaining this information by hand (by querying the respective services/repositories) would be tedious and slow; far better to have a dashboard do the job for the end user.
+
+A dashboard object is a model of the most relevant state to the end-user, in other words it is (quite literally) a view model.
+ It is not a persisted entity, instead it belongs to the application layer.
+
+A view model need not merely aggregate data; it could also provide actions of its own.
+Most likely these actions will be queries and will always ultimately just delegate down to the appropriate domain-layer service/repository.
+But in some cases such view model actions might also modify state of underlying domain entities.
+
+Another common use for view models is to help co-ordinate complex business processes; for example to perform a quarterly invoicing run, or to upload annual interest rates from an Excel spreadsheet.
+In these cases the view model might have some state of its own, but in most cases that state does not need to be persisted per se.
+
+.Desire Lines
+****
+One way to think of application view models is as modelling the "desire line": the commonly-trod path that end-users must follow to get from point A to point B as quickly as possible.
+
+To explain: there are link:http://ask.metafilter.com/62599/Where-the-sidewalk-ends[documented] link:https://sivers.org/walkways[examples] link:http://www.softpanorama.org/People/Wall/larry_wall_articles_and_interviews.shtml[that] architects of university campus will only add in paths some while after the campus buildings are complete: let the pedestrians figure out the routes they want to take.
+The name we like best for this idea is "desire lines", though it has also been called a "desire path", "paving the path" or "paving the sidewalk".
+
+What that means is you should add view models _after_ having built up the domain layer, rather than before.
+These view models pave that commonly-trod path, automating the steps that the end-user would otherwise have to do by hand.
+
+It takes a little practice though, because even when building the domain layer "first", you should still bear in mind what the use cases are that those domain entities are trying to support.
+You certainly _shouldn't_ try to build out a domain layer that could support every conceivable use case before starting to think about view models.
+
+Instead, you should iterate.
+Identify the use case/story/end-user objective that you will deliver value to the business.
+Then build out the minimum domain entities to support that use case (refining the xref:../ugfun/ugfun.adoc#__ugfun_core-concepts_philosophy_domain-driven-design_ubiquitous-language[ubiquitous language] as you go).
+Then, identify if there any view models that could be introduced which would simplify the end-user interactions with the system (perhaps automating several related use cases together).
+****
+
+
+When developing an Apache Isis application you will most likely start off with the persistent domain entities: `Customer`, `Order`, `Product`, and so on.
+For some applications this may well suffice.
+
+However, if the application needs to integrate with other systems, or if the application needs to support reasonably complex business processes, then you may need to look beyond just domain entities; view models are the tool of choice.
+
+[WARNING]
+====
+We strongly recommend that you build your applications from the domain layer up, rather than from the view model down.
+====
+
+
+[[__ugfun_building-blocks_view-models_dtos]]
+== DTOs
+
+DTOs (data transfer objects) are simple classes that (according to link:https://en.wikipedia.org/wiki/Data_transfer_object[wikipedia]) "carry data between processes".
+
+If those two processes are parts of the same overall application (the same team builds and deploys both server and client) then there's generally no need to define a DTO; just access the entities using Apache Isis' xref:../ugvro/ugvro.adoc#[RestfulObjects viewer].
+
+On the other hand, if the client consuming the DTO is a different application -- by which we mean developed/deployed by a different (possible third-party) team -- then the DTOs act as a formal contract between the provider and the consumer.
+In such cases, exposing domain entities over xref:../ugvro/ugvro.adoc#[RestfulObjects] would be "A Bad Thing"(TM) because the consumer would in effect have access to implementation details that could then not be easily changed by the producer.
+
+To support this use case, a view model can be defined such that it can act as a DTO.
+This is done by annotating the class using JAXB annotations; this allows the consumer to obtain the DTO in XML format along with a corresponding XSD schema describing the structure of that XML.
+A discussion of how that might be done using an ESB such as link:http://camel.apache.org[Apache Camel(TM)] follows xref:../ugbtb/ugbtb.adoc#__ugfun_building-blocks_view-models_dtos_consumers[below].
+
+In case it's not obvious, these DTOs are still usable as "regular" view models; they will render in the xref:../ugvw/ugvw.adoc#[Wicket viewer] just like any other.
+In fact (as the xref:../ugbtb/ugbtb.adoc#_ugbtb_view-models_programming-model[programming model] section below makes clear), these JAXB-annotated view models are in many regards the most powerful of all the alternative ways of writing view models.
+
+It's also worth noting that it is also possible to download the XML (or XSD) straight from the UI, useful during development.
+The view model simply needs to implement the xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins_Dto[`Dto`] marker interface; the framework has xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins_Dto[mixins] that contribute the download actions to the view model.
+
+
+[[__ugfun_building-blocks_view-models_dtos_consumers]]
+=== DTO Consumers
+
+The actual consumers of DTOs will generally obtain the XML of the view models either by requesting the XML directly, eg using the xref:../ugvro/ugvro.adoc#[RestfulObjects viewer], or may have the XML sent to them asynchronously using an ESB such as Apache Camel.
+
+In the former case, the consumer requests the DTO by calling the REST API with the appropriate HTTP `Accept` header.
+An appropriate implementation of xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`] can then be used to return the appropriate DTO (as XML).
+
+For the latter case, one design is simply for the application to instantiate the view model, then call the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_JaxbService[`JaxbService`] to obtain its corresponding XML.  This can then be published onto the ESB, for example using an http://activemq.apache.org[Apache ActiveMQ (TM)] queue.
+
+However, rather than try to push all the data that might be needed by any of these external systems in a single XML event (which would require anticipating all the requirements, likely a hopeless task), a better design is to publish only the fact that something of note has changed - ie, that an action on a domain object has been invoked - and then let the consumers call back to obtain other information if required.
+This can once again be done by calling the REST API with an appropriate HTTP `Accept` header.
+
+[TIP]
+====
+This is an example of the link:https://leanpub.com/camel-design-patterns[VETRO pattern] (validate, enrich, transform, route, operate).
+In our case we focus on the validation (to determine the nature of the inbound message, ie which action was invoked), and the enrich (callback to obtain a DTO with additional information required by the consumer).
+====
+
+The (non-ASF) http://github.com/isisaddons/isis-module-publishmq[Isis addons' publishmq] module provides an out-of-the-box solution of this design.
+It provides an implementation of the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`], but which simply publishes instances of xref:../rgcms/rgcms.adoc#_rgcms_schema-aim[`ActionInvocationMemento`] to an ActiveMQ queue.
+Camel (or similar) can then be hooked up to consume these events from this queue, and use a processor to parse the action memento to determine what has changed on the source system.
+Thereafter, a subsequent Camel processor can then call back to the source - via the xref:../ugvro/ugvro.adoc[Restful Objects viewer] - to enrich the message with additional details using a DTO.
+
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure.adoc
deleted file mode 100644
index bd6b28e..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure.adoc
+++ /dev/null
@@ -1,46 +0,0 @@
-[[_ugfun_class-structure]]
-= Class Structure
-: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 works by building a metamodel of the domain objects: entities, domain services, view models and mixins.
-Dependent on the sort of domain object, the class methods represent
-both state -- (single-valued) properties and (multi-valued) collections -- and behaviour -- actions.
-
-More specifically, both entities and view models can have properties, collections and actions, while domain services have just actions.
-Mixins also define only actions, though depending on their semantics they may be rendered as derived properties or collections on the domain object to which they contribute.
-
-In the automatically generated UI a property is rendered as a field.
-This can be either of a value type (a string, number, date, boolean etc) or can be a reference to another entity.
-A collection is generally rendered as a table.
-
-In order for Apache Isis to build its metamodel the domain objects must follow some conventions: what we call the _Apache Isis Programming Model_.
-This is just an extension of the pojo / JavaBean standard of yesteryear: properties and collections are getters/setters, while actions are simply any remaining `public` methods.
-
-Additional metamodel semantics are inferred both imperatively from _supporting methods_ and declaratively from annotations.
-
-In this section we discuss the mechanics of writing domain objects that comply with Apache Isis' programming model.
-
-[TIP]
-====
-In fact, the Apache Isis programming model is extensible; you can teach Apache Isis new programming conventions and you can remove existing ones; ultimately they amount to syntax.
-The only real fundamental that can't be changed is the notion that objects consist of properties, collections and actions.
-
-You can learn more about extending Apache Isis programming model xref:../ugbtb/ugbtb.adoc#_ugbtb_programming-model[here].
-====
-
-
-include::_ugfun_class-structure_properties.adoc[leveloffset=+1]
-include::_ugfun_class-structure_collections.adoc[leveloffset=+1]
-include::_ugfun_class-structure_actions.adoc[leveloffset=+1]
-include::_ugfun_class-structure_inject-services.adoc[leveloffset=+1]
-
-include::_ugfun_class-structure_properties-vs-parameters.adoc[leveloffset=+1]
-
-include::_ugfun_class-structure_domain-services.adoc[leveloffset=+1]
-
-
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_actions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_actions.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_actions.adoc
deleted file mode 100644
index 613cbb9..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_actions.adoc
+++ /dev/null
@@ -1,264 +0,0 @@
-[[_ugfun_class-structure_actions]]
-= Actions
-: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/
-
-
-
-While xref:../ugfun/ugfun.adoc#_ugfun_class-structure_properties[properties] and xref:../ugfun/ugfun.adoc#_ugfun_class-structure_collections[collections] define the state held by a domain object (its "know what" responsibilities), actions define the object's behaviour (its "know how-to" responsibilities).
-
-An application whose domain objects have only/mostly "know-what" responsibilities is pretty dumb: it requires that the end-user know the business rules and doesn't modify the state of the domain objects such that they are invalid (for example, an "end date" being before a "start date").
-Such applications are often called CRUD applications (create/read/update/delete).
-
-In more complex domains, it's not realistic/feasible to expect the end-user to have to remember all the different business rules that govern the valid states for each domain object.
-So instead actions allow those business rules to be encoded programmatically.
-An Apache Isis application doesn't try to constrain the end-user as to way in which they interact with the user (it doesn't attempt to define a rigid business process) but it does aim to ensure that business rule invariants are maintained, that is that business objects aren't allowed to go into an invalid state.
-
-For simple domain applications, you may want to start prototyping only with properties, and only later introduce actions (representing the most common business operations).
-But an alternative approach, recommended for more complex applications, is actually to start the application with all properties non-editable.
-Then, as the end-user requires the ability to modify some state, there is a context in which to ask the question "why does this state need to change?" and "are their any side-effects?" (ie, other state that changes at the same time, or other behaviour that should occur).
-If the state change is simple, for example just being able to correct an invalid address, or adding a note or comment, then that can probably be modelled as a simple editable property.
-But if the state change is more complex, then most likely an action should be used instead.
-
-
-[[__ugfun_class-structure_actions_defining-actions]]
-== Defining actions
-
-Broadly speaking, actions are all the `public` methods that are not getters or setters which represent properties or collections.
-This is a slight simplification; there are a number of other method prefixes (such as `hide` or `validate`) that represent xref:../ugfun/ugfun.adoc#_ugfun_business-rules[business rules]); these also not treated as actions.
-And, any method that are annotated with `@Programmatic` will also be excluded.
-But by and large, all other methods such as `placeOrder(...)` or `approveInvoice(...)` will be treated as actions.
-
-For example:
-
-[source,java]
-----
-@Action(semantics=SemanticsOf.IDEMPOTENT)       // <1>
-public ShoppingBasket addToBasket(
-        Product product,
-        @ParameterLayout(named="Quantity")      // <2>
-        int quantity
-        ) {
-    ...
-    return this;
-}
-----
-<1> `@Action` annotation is optional but used to specify additional domain semantics (such as being idempotent).
-<2> The names of action parameters (as rendered in the UI) will by default be the parameter types, not the paramter names.
-For the `product` parameter this is reasonable, but not so for the `quantity` parameter (which would by default show up with a name of "int".
-The `@ParameterLayout` annotation provides a UI hint to the framework.
-
-[TIP]
-====
-The (non-ASF) Isis addons' http://github.com/isisaddons/isis-metamodel-paraname8[paraname8] metamodel extension allows the parameter name to be used in the UI, rather than the type.
-====
-
-
-[[__ugfun_class-structure_actions_reference-parameter-types]]
-== (Reference) Parameter types
-
-Parameter types can be value types or reference types.
-In the case of primitive types, the end-user can just enter the value directly through the parameter field.
-In the case of reference types however (such as `Product`), a drop-down must be provided from which the end-user to select.
-This is done using either a supporting xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_choices[`choices`] or xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete`] method.
-The "choices" is used when there is a limited set of options, while "autoComplete" is used when there are large set of options such that the end-user must provide some characters to use for a search.
-
-For example, the `addToBasket(...)` action shown above might well have a :
-
-[source,java]
-----
-@Action(semantics=SemanticsOf.IDEMPOTENT)
-public ShoppingBasket addToBasket(
-        Product product,
-        @ParameterLayout(named="Quantity")
-        int quantity
-        ) {
-    ...
-    return this;
-}
-public List<Product> autoComplete0AddToBasket(              // <1>
-    @MinLength(3)                                           // <2>
-    String searchTerm) {
-    return productRepository.find(searchTerm);              // <3>
-}
-@javax.inject.Inject
-ProductRepository productRepository;
-----
-<1> Supporting `autoComplete` method.
-The "0" in the name means that this corresponds to parameter 0 of the "addToBasket" action (ie `Product`).
-It is also required to return a Collection of that type.
-<2> The xref:../rgant/rgant.adoc#_rgant_MinLength[`@MinLength`] annotation defines how many characters the end-user must enter before performing a search.
-<3> The implementation delegates to an injected repository service.  This is typical.
-
-Note that it is also valid to define "choices" and "autoComplete" for value types (such as `quantity`, above); it just isn't as common to do so.
-
-[[__ugfun_class-structure_actions_reference-parameter-types_removing-boilerplate]]
-=== Removing boilerplate
-
-To save having to define an `autoCompleteNXxx(...)` method everywhere that a reference to a particular type (such as `Product`) appears as an action parameter, it is also possible to use the `@DomainObject` annotation on `Product` itself:
-
-[source,java]
-----
-@DomainObject(
-    autoCompleteRepository=ProductRepository.class          // <1>
-    autoCompleteAction="find"                               // <2>
-)
-public class Product ... {
-    ...
-}
-----
-<1> Whenever an action parameter requiring a `Product` is defined, provide an autoComplete drop-down automatically
-<2> Use the "find" method of `ProductRepository` (rather than the default name of "autoComplete")
-
-(As noted above), if the number of available instances of the reference type is a small number (in other words, all of which could comfortably be shown in a drop-down) then instead the `choicesNXxx()` supporting method can be used.
-This too can be avoided by annotating the referenced class.
-
-For example, suppose we have an action to specify the `PaymentMethodType`, where there are only 10 or so such (Visa, Mastercard, Amex, Paypal etc).
-We could define this as:
-
-[source,java]
-----
-public Order payUsing(PaymentMethodType type) {
-    ...
-}
-----
-
-where `PaymentMethodType` would be annotated using:
-
-[source,java]
-----
-@DomainObject(
-    bounded=true                            // <1>
-)
-public class PaymentMethodType ... {
-    ...
-}
-----
-<1> only a small (ie "bounded") number of instances available, meaning that the framework should render all in a drop-down.
-
-
-[[__ugfun_class-structure_actions_collection-parameter-types]]
-== Collection Parameter types
-
-Action parameters can also be collections of values (for example `List<String>`), or can be collections of references (such as `List<Customer>`).
-
-For example:
-
-[source,java]
-----
-@Action(semantics=SemanticsOf.IDEMPOTENT)
-public ShoppingBasket addToBasket(
-        List<Product> products,
-        @ParameterLayout(named="Quantity") int quantity
-        ) {
-    ...
-    return this;
-}
-public List<Product> autoComplete0AddToBasket(@MinLength(3) String searchTerm) {
-    return ...
-}
-----
-
-As the example suggests, any collection parameter type must provide a way to select items, either by way of a "choices" or "autoComplete" supporting method or alternatively defined globally using xref:../rgant/rgant.adoc#_rgant_DomainObject[`@DomainObject`] on the referenced type (described xref:../ugfun/ugfun.adoc#__ugfun_class-structure_actions_reference-parameter-types_removing-boilerplate[above]).
-
-
-[[__ugfun_class-structure_actions_optional-parameters]]
-== Optional Parameters
-
-Whereas the xref:../ugfun/ugfun.adoc#__ugfun_class-structure_properties_optional-properties[optionality of properties] is defined using xref:../rgant/rgant.adoc#_rgant_Column_allowsNull[`@javax.jdo.annotations.Column#allowsNull()`], that JDO annotation cannot be applied to parameter types.
-Instead, either the xref:../rgant/rgant.adoc#_rgant_Nullable[`@Nullable`] annotation or the xref:../rgant/rgant.adoc#_rgant_Parameter_optionality[`@Parameter#optionality()`]  annotation/attribute is used.
-
-For example:
-
-[source,java]
-----
-@javax.jdo.annotations.Column(allowsNull="true")                // <1>
-@lombok.Getter @lombok.Setter
-private LocalDate shipBy;
-
-public Order invoice(
-                PaymentMethodType paymentMethodType,
-                @Nullable                                       // <2>
-                @ParameterLayout(named="Ship no later than")
-                LocalDate shipBy) {
-    ...
-    setShipBy(shipBy)
-    return this;
-}
-----
-<1> Specifies the property is optional.
-<2> Specifies the corresponding parameter is optional.
-
-See also xref:../ugfun/ugfun.adoc#_ugfun_class-structure_properties-vs-parameters[properties vs parameters].
-
-[[__ugfun_class-structure_actions_string-parameters]]
-== ``String`` Parameters (Length)
-
-Whereas the xref:../ugfun/ugfun.adoc#__ugfun_class-structure_properties_datatypes_strings[length of string properties] is defined using xref:../rgant/rgant.adoc#_rgant_Column_length[`@javax.jdo.annotations.Column#length()`], that JDO annotation cannot be applied to parameter types.
-Instead, the xref:../rgant/rgant.adoc#_rgant_Parameter_maxLength[`@Parameter#maxLength()`] annotation/attribute is used.
-
-For example:
-
-[source,java]
-----
-@javax.jdo.annotations.Column(length=50)                // <1>
-@lombok.Getter @lombok.Setter
-private String firstName;
-
-@javax.jdo.annotations.Column(length=50)
-@lombok.Getter @lombok.Setter
-private String lastName;
-
-public Customer updateName(
-                @Parameter(maxLength=50)                // <2>
-                @ParameterLayout(named="First name")
-                String firstName,
-                @Parameter(maxLength=50)
-                @ParameterLayout(named="Last name")
-                String lastName) {
-    setFirstName(firstName);
-    setLastName(lastName);
-    return this;
-}
-----
-<1> Specifies the property length using the JDO xref:../rgant/rgant.adoc#_rgant_Column_length[`@Column#length()`] annotation
-<2> Specifies the parameter length using the (Apache Isis) xref:../rgant/rgant.adoc#_rgant_Parameter_maxLength[`@Parameter#maxLength()`] annotation
-
-[IMPORTANT]
-====
-Incidentally, note in the above example that the new value is assigned to the properties using the setter methods; the action does not simply set the instance field directly.
-This is important, because it allows JDO/DataNucleus to keep track that this instance variable is "dirty" and so needs flushing to the database table before the transaction completes.
-====
-
-See also xref:../ugfun/ugfun.adoc#_ugfun_class-structure_properties-vs-parameters[properties vs parameters].
-
-[[__ugfun_class-structure_actions_bigdecimal-parameters]]
-== ``BigDecimal``s (Precision)
-
-Whereas the xref:../ugfun/ugfun.adoc#__ugfun_class-structure_properties_datatypes_bigdecimals[precision of BigDecimal properties] is defined using xref:../rgant/rgant.adoc#_rgant_Column_scale[`@javax.jdo.annotations.Column#scale()`], that JDO annotation cannot be applied to parameter types.
-Instead, the xref:../rgant/rgant.adoc#_rgant_Digits_fraction[`@javax.validation.constraints.Digits#fraction()`] annotation/attribute is used.
-
-For example:
-
-[source,java]
-----
-@javax.jdo.annotations.Column(scale=2)                              // <1>
-@lombok.Getter @lombok.Setter
-private BigDecimal discountRate;
-
-public Order updateDiscount(
-                @javax.validation.constraints.Digits(fraction=2)    // <2>
-                @ParameterLayout(named="Discount rate")
-                String discountRate) {
-    setDiscountRate(discountRate);
-    return this;
-}
-----
-<1> Specifies the property precision using xref:../rgant/rgant.adoc#_rgant_Column_scale[`@Column#scale()`]
-<2> Specifies the corresponding parameter precision using xref:../rgant/rgant.adoc#_rgant_Digits_fraction[`@Digits#fraction()`].
-
-See also xref:../ugfun/ugfun.adoc#_ugfun_class-structure_properties-vs-parameters[properties vs parameters].
-
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_collections.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_collections.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_collections.adoc
deleted file mode 100644
index a3e09da..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_collections.adoc
+++ /dev/null
@@ -1,121 +0,0 @@
-[[_ugfun_class-structure_collections]]
-= Collections
-: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/
-
-
-A collection is an instance variable of a domain object, of a collection type that holds references to other domain objects.
-For example, a `Customer` may have a collection of ``Order``s).
-
-It's ok for a xref:../ugfun/ugfun.adoc#__ugfun_class-structure_class-definition_entities[domain entity] to reference another domain entity, and for a xref:../ugfun/ugfun.adoc#__ugfun_class-structure_class-definition_view-models[view model] to reference both view model and domain entities.
-However, it isn't valid for a domain entity to hold a persisted reference to view model (DataNucleus will not know how to persist that view model).
-
-Formally speaking, a collection is simply a regular JavaBean getter, returning a collection type (subtype of `java.util.Collection`).
-Most collections (those that are modifiable) will also have a setter and (if persisted) a backing instance field.
-And collections properties will also have a number of annotations:
-
-* Apache Isis defines its own set own `@Collection` annotation for capturing domain semantics.
-It also provides a `@CollectionLayout` for UI hints (though the information in this annotation may instead be provided by a supplementary xref:../ugvw/ugvw.adoc#_ugvw_layout[`.layout.xml`] file
-
-* the collections of domain entities are often annotated with various JDO/DataNucleus annotations, most notable `javax.jdo.annotations.Persistent`.
-This and other annotations can be used to specify if the association is bidirectional, and whether to define a link table or not to hold foreign key columns.
-
-* for the collections of view models, then JAXB annotations such as `@javax.xml.bind.annotation.XmlElementWrapper` and `@javax.xml.bind.annotation.XmlElement` will be present
-
-Apache Isis recognises some of these annotations for JDO/DataNucleus and JAXB and infers some domain semantics from them (for example, the maximum allowable length of a string property).
-
-Unlike xref:../ugfun/ugfun.adoc#_ugfun_class-structure_properties[properties], the framework (at least, the xref:../ugvw/ugvw.adoc[Wicket viewer]) does not allow collections to be "edited".
-Instead, xref:../ugfun/ugfun.adoc#_ugfun_class-structure_actions[action]s can be written that will modify the contents of the collection as a side-effect.
-For example, a `placeOrder(...)` action will likely add an `Order` to the `Customer#orders` collection.
-
-Since writing getter and setter methods adds quite a bit of boilerplate, it's common to use link:https://projectlombok.org/[Project Lombok] to code generate these methods at compile time (using Java's annotation processor) simply by adding the `@lombok.Getter` and `@lombok.Setter` annotations to the field.
-
-
-
-[[__ugfun_class-structure_collections_mapping-bidir-1m]]
-== Mapping bidir 1:m
-
-Bidirectional one-to-many collections are one of the most common types of associations between two entities.
-In the parent object, the collection can be defined as:
-
-[source,java]
-----
-public class ParentObject
-        implements Comparable<ParentObject>{
-
-    @javax.jdo.annotations.Persistent(
-        mappedBy = "parent",                                                // <1>
-        dependentElement = "false"                                          // <2>
-    )
-    @Collection                                                             // <3>
-    @lombok.Getter @lombok.Setter
-    private SortedSet<ChildObject> children = new TreeSet<ChildObject>();   // <4>
-
-}
-----
-<1> indicates a bidirectional association; the foreign key pointing back to the `Parent` will be in the table for `ChildObject`
-<2> disable cascade delete
-<3> (not actually required in this case, because no attributes are set, but acts as a useful reminder that this collection will be rendered in the UI by Apache Isis)
-<4> uses a `SortedSet` (as opposed to some other collection type; discussion below)
-
-while in the child object you will have:
-
-[source,java]
-----
-public class ChildObject
-        implements Comparable<ChildObject> {    // <1>
-
-    @javax.jdo.annotations.Column(
-        allowsNull = "false"                    // <2>
-    )
-    @Property(editing = Editing.DISABLED)       // <3>
-    @lombok.Getter @lombok.Setter
-    private ParentObject parent;
-}
-----
-<1> implements `Comparable` because is mapped using a `SortedSet`
-<2> mandatory; every child must reference its parent
-<3> cannot be edited directly
-
-Generally speaking you should use `SortedSet` for collection types (as opposed to `Set`, `List` or `Collection`).
-JDO/Datanucleus does support the mapping of these other types, but RDBMS are set-oriented, so using this type introduces the least friction.
-
-[NOTE]
-====
-For further details on mapping associations, see the JDO/DataNucleus documentation for link:http://www.datanucleus.org/products/accessplatform_4_1/jdo/orm/one_to_many.html[one-to-many] associations, link:http://www.datanucleus.org/products/accessplatform_4_1/jdo/orm/many_to_one.html[many-to-one] associations, link:http://www.datanucleus.org/products/accessplatform_4_1/jdo/orm/many_to_many.html[many-to-many] associations, and so on.
-
-Also, while JDO/DataNucleus itself supports `java.util.Map` as a collection type, this is not supported by Apache Isis.
-If you do wish to use this collection type, then annotate the getter with `@Programmatic` so that it is ignored by the Apache Isis framework.
-====
-
-
-
-== Value vs Reference Types
-
-Apache Isis can (currently) only provide a UI for collections of references.
-While you can use DataNucleus to persist collections/arrays of value types, such properties must be annotated as `@Programmatic` so that they are ignored by Apache Isis.
-
-If you want to visualize an array of value types in Apache Isis, then one option is to wrap value in a view model, as explained xref:../ugfun/ugfun.adoc#_ugbtb_hints-and-tips_simulating-collections-of-values[elsewhere].
-
-
-
-[[__ugfun_class-structure_collections_derived-collections]]
-== Derived Collections
-
-A derived collection is simply a getter (no setter) that returns a `java.util.Collection` (or subtype).
-
-While derived properties and derived collections typically "walk the graph" to associated objects, there is nothing to prevent the returned value being the result of invoking a repository (domain service) action.
-
-For example:
-
-[source,java]
-----
-public class Customer {
-    ...
-    public List<Order> getMostRecentOrders() {
-        return orderRepo.findMostRecentOrders(this, 5);
-    }
-}
-----
-

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_domain-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_domain-services.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_domain-services.adoc
deleted file mode 100644
index ce7c3e7..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_domain-services.adoc
+++ /dev/null
@@ -1,155 +0,0 @@
-[[_ugfun_class-structure_domain-services]]
-= Domain Services
-: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/
-
-
-This section looks at the programming conventions of writing your own domain services.
-
-
-== Typical Implementation
-
-Domain services are generally singletons that are automatically injected into other domain services.
-A very common usage is as a repository (to find/locate existing entities) or as a factory (to create new instances of entities).
-But services can also be exposed in the UI as top-level menus; and services are also used as a bridge to access technical resources (eg rendering a document object as a PDF).
-
-The Apache Isis framework itself also provides a large number of number of domain services, catalogued in the xref:../rgsvc/rgsvc.adoc#[Domain Services Reference Guide].
-Some of these are APIs (intended to be called by your application's own domain objects) and some are SPIs (implemented by your application and called by the framework, customising the way it works).
-
-The following is a typical menu service:
-
-[source,java]
-----
-@DomainService(                                                 // <1>
-        nature = NatureOfService.VIEW_MENU_ONLY
-)
-@DomainServiceLayout(                                           // <2>
-        named = "Simple Objects",
-        menuOrder = "10"
-)
-public class SimpleObjectMenu {
-
-    ...
-
-    @Action(semantics = SemanticsOf.SAFE)
-    @ActionLayout(bookmarking = BookmarkPolicy.AS_ROOT)
-    @MemberOrder(sequence = "2")
-    public List<SimpleObject> findByName(                       // <3>
-            @ParameterLayout(named="Name")
-            final String name
-    ) {
-        return simpleObjectRepository.findByName(name);
-    }
-
-    @javax.inject.Inject
-    SimpleObjectRepository simpleObjectRepository;              // <4>
-}
-----
-<1> The (Apache Isis) `@DomainService` annotation is used to identify the class as a domain service.
-Apache Isis scans the classpath looking for classes with this annotation, so there very little configuration other than to tell the framework which packages to scan underneath.
-The `VIEW_MENU_ONLY` nature indicates that this service's actions should be exposed as menu items.
-<2> The (Apache Isis) `@DomainServiceLayout` annotation provides UI hints.
-In the example above the menu is named "Simple Objects" (otherwise it would have defaulted to "Simple Object Menu", based on the class name, while the `menuOrder` attribute determines the order of the menu with respect to other menu services.
-<3> The `findByName` method is annotated with various Apache Isis annotations (`@Action`, `@ActionLayout` and `@MemberOrder`) and is itself rendered in the UI as a "Find By Name" menu item underneath the "Simple Objects" menu.
-The implementation delegates to an `SimpleObjectRepository` service, which is injected.
-<4> The `javax.inject.Inject` annotation instructs Apache Isis framework to inject the `SimpleObjectRepository` service into this domain object.
-The framework can inject into not just other domain services but will also automatically into domain entities and view models.
-There is further discussion of service injection xref:../ugfun/ugfun.adoc#_ugfun_class-structure_inject-services[below].
-
-
-
-
-== Scoped services
-
-By default all domain services are considered to be singletons, and thread-safe.
-
-Sometimes though a service's lifetime is applicable only to a single request; in other words it is request-scoped.
-
-The CDI annotation xref:../rgant/rgant.adoc#_rgant-RequestScoped[`@javax.enterprise.context.RequestScoped`] is used to indicate this fact:
-
-[source,java]
-----
-@javax.enterprise.context.RequestScoped
-public class MyService extends AbstractService {
-    ...
-}
-----
-
-The framework provides a number of request-scoped services, include a xref:../rgsvc/rgsvc.adoc#_rgsvc_api_Scratchpad[`Scratchpad`] service query results caching through the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_QueryResultsCache[`QueryResultsCache`], and support for co-ordinating bulk actions through the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ActionInvocationContext[`ActionInvocationContext`] service.  See the xref:../rgsvc/rgsvc.adoc[domain services] reference guide for further details.
-
-
-
-
-== Registering domain services
-
-The easiest way to register domain services is using xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`] to specify the modules
-which contain xref:../rgant/rgant.adoc#_rgant-DomainService[`@DomainService`]-annotated classes.
-
-For example:
-
-[source,ini]
-----
-public class MyAppManifest implements AppManifest {
-    public List<Class<?>> getModules() {
-        return Arrays.asList(
-                ToDoAppDomainModule.class,
-                ToDoAppFixtureModule.class,
-                ToDoAppAppModule.class,
-                org.isisaddons.module.audit.AuditModule.class);
-    }
-    ...
-}
-----
-
-will load all services in the packages underneath the four modules listed.
-
-An alternative (older) mechanism is to registered domain services in the `isis.properties` configuration file, under `isis.services` key (a comma-separated list); for example:
-
-[source,ini]
-----
-isis.services = com.mycompany.myapp.employee.Employees\,
-                com.mycompany.myapp.claim.Claims\,
-                ...
-----
-
-This will then result in the framework instantiating a single instance of each of the services listed.
-
-If all services reside under a common package, then the `isis.services.prefix` can specify this prefix:
-
-[source,ini]
-----
-isis.services.prefix = com.mycompany.myapp
-isis.services = employee.Employees,\
-                claim.Claims,\
-                ...
-----
-
-This is quite rare, however; you will often want to use default implementations of domain services that are provided by the framework and so will not reside under this prefix.
-
-Examples of framework-provided services (as defined in the applib) include clock, auditing, publishing, exception handling, view model support, snapshots/mementos, and user/application settings management; see the xref:../rgsvc/rgsvc.adoc[domain services] reference guide for further details.
-
-
-
-== Initialization
-
-Services can optionally declare lifecycle callbacks to initialize them (when the app is deployed) and to shut them down (when the app is undeployed).
-
-An Apache Isis session _is_ available when initialization occurs (so services can interact with the object store, for example).
-
-
-The framework will call any `public` method annotated with xref:../rgant/rgant.adoc#_rgant-PostConstruct[`@PostConstruct`] with either no arguments of an argument of type `Map<String,String>`
-
-or
-
-In the latter case, the framework passes in the configuration (`isis.properties` and any other component-specific configuration files).
-
-
-Shutdown is similar; the framework will call any method annotated with xref:../rgant/rgant.adoc#_rgant-PreDestroy[`@PreDestroy`].
-
-
-
-== The getId() method
-
-Optionally, a service may provide a xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_getId[`getId()`] method.  This method returns a logical identifier for a service, independent of its implementation.
-

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_inject-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_inject-services.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_inject-services.adoc
deleted file mode 100644
index fb09fe1..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_inject-services.adoc
+++ /dev/null
@@ -1,103 +0,0 @@
-[[_ugfun_class-structure_inject-services]]
-= Injecting services
-: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 autowires (automatically injects) domain services into each entity, as well as into the domain services themselves, using either method injection or field injection.
-The framework defines many additional services (such as xref:../rgsvc/rgsvc.adoc#_rgsvc_api_RepositoryService[`RepositoryService`]); these are injected in exactly the same manner.
-
-Sometimes there may be multiple services that implement a single type.
-This is common for example for SPI service, whereby one module defines an SPI service, and other module(s) in the application implement that service.
-To support this, the framework also allows lists of services to be injected.
-
-When there are multiple service implementations of a given type, the framework will inject the service with highest priority, as defined through xref:../rgant/rgant.adoc#_rgant_DomainService_menuOrder[`@DomainService#menuOrder()`] (even for domain services that are not menus), lowest first.
-If a list of services is injected, then that list will be ordered according to `menuOrder`, again lowest first.
-
-
-
-[NOTE]
-====
-Isis currently does _not_ support qualified injection of services; the domain service of each type must be distinct from any other.
-
-If you find a requirement to inject two instances of type `SomeService`, say, then the work-around is to create trivial subclasses `SomeServiceA` and `SomeServiceB` and inject these instead.
-====
-
-
-== Field Injection
-
-Field injection is recommended, using the `@javax.inject.Inject` annotation.
-For example:
-
-[source,java]
-----
-public class Customer {
-    ...
-    @javax.inject.Inject
-    OrderRepository orderRepository;
-}
-----
-
-To inject a list of services, use:
-
-[source,java]
-----
-public class DocumentService {
-    ...
-    @javax.inject.Inject
-    List<PaperclipFactory> paperclipFactories;
-}
-----
-
-We recommend using default rather than `private` visibility so that the field can be mocked out within unit tests (placed in the same package as the code under test).
-
-
-
-
-== Method Injection
-
-The framework also supports two forms of method injection.
-All that is required to inject a service into a entity/service is to provide an appropriate method or field.
-The name of the method does not matter, only that it is prefixed either `set` or `inject`, is public, and has a single parameter of the correct type.
-
-For example:
-
-[source,java]
-----
-public class Customer {
-    private OrderRepository orderRepository;
-    public void setOrderRepository(OrderRepository orderRepository) {
-        this.orderRepository = orderRepository;
-    }
-    ...
-}
-----
-
-or alternatively, using 'inject' as the prefix:
-
-[source,java]
-----
-public class Customer {
-    private OrderRepository orderRepository;
-    public void injectOrderRepository(OrderRepository orderRepository) {
-        this.orderRepository = orderRepository;
-    }
-    ...
-}
-----
-
-Lists of services can be injected in a similar manner.
-
-Note that the method name can be anything; it doesn't need to be related to the type being injected.
-
-
-== Constructor injection
-
-Simply to note that constructor injection is _not_ supported by Apache Isis (and is unlikely to be, because the JDO specification for entities requires a no-arg constructor).
-
-
-
-
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_properties-vs-parameters.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_properties-vs-parameters.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_properties-vs-parameters.adoc
deleted file mode 100644
index a0a926a..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_properties-vs-parameters.adoc
+++ /dev/null
@@ -1,38 +0,0 @@
-[[_ugfun_class-structure_properties-vs-parameters]]
-= Properties vs Parameters
-: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/
-
-
-In many cases the value types of properties and of action parameters align.
-For example, a `Customer` entity might have a `surname` property, and there might also be corresponding `changeSurname`.
-Ideally we want the surname property and surname action parameter to use the same value type.
-
-Since JDO/DataNucleus handles persistence, its annotations are requiredto specify semantics such as optionality or maximum length on properties.
-However, they cannot be applied to action parameters.
-It is therefore necessary to use Apache Isis' equivalent annotations for action parameters.
-
-The table below summarises the equivalence of some of the most common cases.
-
-.Comparing annotations of Properties vs Action Parameters
-[cols="2,3,3", options="header"]
-|===
-|value type/semantic
-|(JDO) property
-|action parameter
-
-|string (length)
-|`@javax.jdo.annotations.Column(length=50)`
-|`@javax.jdo.annotations.Parameter(maxLength=50)`
-
-|big decimal (precision)
-|`@javax.jdo.annotations.Column(scale=2)`
-|`@javax.validation.constraints.Digits(fraction=2)`
-
-|optionality
-|`@Column(allowsNull="true")`
-|`@Nullable` or `ParameterLayout(optionality=Optionality.OPTIONAL`) (also `@Optional`, now deprecated)
-|===
-
-

[23/58] [abbrv] isis git commit: ISIS-1521: working on ugfun.adoc

[da...@apache.org]

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_properties.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_properties.adoc
deleted file mode 100644
index ecff327..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_properties.adoc
+++ /dev/null
@@ -1,369 +0,0 @@
-[[_ugfun_class-structure_properties]]
-= Property
-: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/
-
-
-A property is an instance variable of a domain object, of a scalar type, that holds some state about either a xref:../ugfun/ugfun.adoc#__ugfun_class-structure_class-definition_entities[domain entity] or a xref:../ugfun/ugfun.adoc#__ugfun_class-structure_class-definition_view-models[view model].
-
-For example, a ``Customer``'s `firstName` would be a property, as would their `accountCreationDate` that they created their account.
-All properties have at least a "getter" method, and most properties have also a "setter" method (meaning that they are mutable).
-Properties that do _not_ have a setter method are derived properties, and so are not persisted.
-
-Formally speaking, a property is simply a regular JavaBean getter, returning a scalar value recognized by the framework.
-Most properties (those that are editable/modifiable) will also have a setter and (if persisted) a backing instance field.
-And most properties will also have a number of annotations:
-
-* Apache Isis defines its own set own `@Property` annotation for capturing domain semantics.
-It also provides a `@PropertyLayout` for UI hints (though the information in this annotation may instead be provided by a supplementary xref:../ugvw/ugvw.adoc#_ugvw_layout[`.layout.xml`] file
-
-* the properties of domain entities are often annotated with the JDO/DataNucleus `@javax.jdo.annotations.Column` annotation.
-For property references, there may be other annotations to indicate whether the reference is bidirectional.
-It's also possible (using annotations) to define a link table to hold foreign key columns.
-
-* for the properties of view models, then JAXB annotations such as `@javax.xml.bind.annotation.XmlElement` will be present
-
-Apache Isis recognises some of these annotations for JDO/DataNucleus and JAXB and infers some domain semantics from them (for example, the maximum allowable length of a string property).
-
-Since writing getter and setter methods adds quite a bit of boilerplate, it's common to use link:https://projectlombok.org/[Project Lombok] to code generate these methods at compile time (using Java's annotation processor) simply by adding the `@lombok.Getter` and `@lombok.Setter` annotations to the field.
-The xref:guides/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] uses this approach.
-
-
-[[__ugfun_class-structure_properties_value-vs-reference-types]]
-== Value vs Reference Types
-
-Properties can be either a value type (strings, int, date and so on) or be a reference to another object (for example, an `Order` referencing the `Customer` that placed it).
-
-For example, to map a string value type:
-
-[source,java]
-----
-@lombok.Getter @lombok.Setter       // <1>
-private String notes;
-----
-<1> using link:https://projectlombok.org/[Project Lombok] annotations to reduce boilerplate
-
-You could also add the `@Property` annotation if you wished:
-
-[source,java]
-----
-@Property
-@lombok.Getter @lombok.Setter
-private String notes;
-----
-
-Although in this case it is not required (none of its attributes have been set).
-
-Or to map a reference type:
-
-[source,java]
-----
-@lombok.Getter @lombok.Setter
-private Customer customer;
-----
-
-It's ok for a xref:../ugfun/ugfun.adoc#__ugfun_class-structure_class-definition_entities[domain entity] to reference another domain entity, and for a xref:../ugfun/ugfun.adoc#__ugfun_class-structure_class-definition_view-models[view model] to reference both view model and domain entities.
-However, it isn't valid for a domain entity to hold a persisted reference to view model (DataNucleus will not know how to persist that view model).
-
-[NOTE]
-====
-For further details on mapping associations, see the JDO/DataNucleus documentation for link:http://www.datanucleus.org/products/accessplatform_4_1/jdo/orm/one_to_many.html[one-to-many] associations, link:http://www.datanucleus.org/products/accessplatform_4_1/jdo/orm/many_to_one.html[many-to-one] associations, link:http://www.datanucleus.org/products/accessplatform_4_1/jdo/orm/many_to_many.html[many-to-many] associations, and so on.
-====
-
-For domain entities, the annotations for mapping value types tend to be different for properties vs action parameters, because JDO annotations are only valid on properties.
-The table in the xref:../ugfun/ugfun.adoc#_ugfun_class-structure_properties-vs-parameters[Properties vs Parameters] section provides a handy reference of each.
-
-
-[[__ugfun_class-structure_properties_optional-properties]]
-== Optional Properties
-
-(For domain entities) JDO/DataNucleus' default is that a property is assumed to be mandatory if it is a primitive type (eg `int`, `boolean`), but optional if a reference type (eg `String`, `BigDecimal` etc).
-To override optionality in JDO/DataNucleus the `@Column(allowsNull="...")` annotations is used.
-
-Apache Isis on the other hand assumes that all properties (and action parameters, for that matter) are mandatory, not optional.
-These defaults can also be overridden using Apache Isis' own annotations, specifically `@Property(optionality=...)`, or (because it's much less verbose) using `@javax.annotation.Nullable`.
-
-These different defaults can lead to incompatibilities between the two frameworks.
-To counteract that, Apache Isis also recognizes and honours JDO's `@Column(allowsNull=...)`.
-
-For example, you can write:
-
-[source,java]
-----
-@javax.jdo.annotations.Column(allowsNull="true")
-@lombok.Getter @lombok.Setter
-private LocalDate date;
-----
-
-rather than the more verbose:
-
-[source,java]
-----
-@javax.jdo.annotations.Column(allowsNull="true")
-@Property(optionality=Optionality.OPTIONAL)
-@lombok.Getter @lombok.Setter
-private LocalDate date;
-----
-
-The framework will search for any incompatibilities in optionality (whether specified explicitly or defaulted implicitly) between Isis' defaults and DataNucleus, and refuse to boot if any are found (fail fast).
-
-[[__ugfun_class-structure_properties_editable-properties]]
-== Editable Properties
-
-Apache Isis provides the capability to allow individual properties to be modified.
-This is specified using the `@Property(editing=...)` attribute.
-
-For example:
-
-[source,java]
-----
-@Property(editing = Editing.ENABLED)
-@lombok.Getter @lombok.Setter
-private String notes;
-----
-
-If this is omitted then whether editing is enabled or disabled is defined globally, in the `isis.properties` configuration file; see xref:../rgcfg/rgcfg.adoc#__rgcfg_configuring-core_isis-objects-editing[reference configuration guide] for further details.
-
-
-[[__ugfun_class-structure_properties_ignoring-properties]]
-== Ignoring Properties
-
-By default Apache Isis will automatically render all properties in the xref:../ugvw/ugvw.adoc[UI] or in the xref:../ugvro/ugvro.adoc[REST API].
-To get Apache Isis to ignore a property (exclude it from its metamodel), annotate the getter using `@Programmatic`.
-
-Similarly, you can tell JDO/DataNucleus to ignore a property using the `@javax.jdo.annotations.NotPersistent` annotation.
-This is independent of Apache Isis; in other words that property will still be rendered in the UI (unless also annotated with `@Programmatic`).
-
-For view models, you can tell JAXB to ignore a property using the `@javax.xml.bind.annotation.XmlTransient` annotation.
-Again, this is independent of Apache Isis.
-
-
-[[__ugfun_class-structure_properties_derived-properties]]
-== Derived Properties
-
-Derived properties are those with a getter but no setter.
-Provided that the property has not been annotated with `@Programmatic`, these will still be rendered in the UI, but they will be read-only (not editable) and their state will not be persisted.
-
-Subtly different, it is also possible to have non-persisted but still editable properties.
-In this case you will need a getter and a setter, but with the getter annotated using `@NotPersistent`.
-The implementation of these getters and setters will most likely persist state using other properties (which might be hidden from view using `@Programmatic`).
-
-For example:
-
-[source,java]
-----
-@javax.jdo.annotations.NotPersistent
-@Property(editing=Editing.ENABLED)
-public String getAddress() { return addressService.toAddress( getLatLong() ); }             // <1>
-public void setAddress(String address) { setLatLong(addressService.toLatLong(address)); }
-
-@javax.jdo.annotations.Column
-private String latLong;
-@Programmatic
-public String getLatLong() { return latLong; }                                              // <2>
-public void setLatLong(String latLong) { this.latLong = latLong; }
-
-@javax.inject.Inject
-AddressService addressService;                                                              // <3>
-----
-<1> the representation of the address, in human readable form, eg "10 Downing Street, London, UK"
-<2> the lat/long representation of the address, eg "51.503363;-0.127625"
-<3> an injected service that can convert to/from address and latLong.
-
-
-
-[[__ugfun_class-structure_properties_datatypes]]
-== Data types
-
-This section shows specific considerations for various datatypes, in particular how to annotate them for DataNucleus mapping to the persistence object store.
-
-
-
-[[__ugfun_class-structure_properties_datatypes_strings]]
-=== ``String``s (Length)
-
-By default JDO/DataNucleus will map string properties to a `VARCHAR(255)`.
-To limit the length, use the `@Column(length=...)` annotation.
-
-For example:
-
-[source,java]
-----
-@javax.jdo.annotations.Column(length=50)
-@lombok.Getter @lombok.Setter
-private String firstName
-----
-
-This is a good example of a case where Apache Isis infers domain semantics from the JDO annotation.
-
-
-
-[[__ugfun_class-structure_properties_datatypes-joda-dates]]
-=== JODA Dates
-
-Isis' JDO objectstore bundles DataNucleus' http://www.datanucleus.org/documentation/products/plugins.html[built-in support] for Joda `LocalDate` and `LocalDateTime` datatypes, meaning that entity properties of these types will be persisted as appropriate data types in the database tables.
-
-It is, however, necessary to annotate your properties with `@javax.jdo.annotations.Persistent`, otherwise the data won't actually be persisted.
-See the link:http://db.apache.org/jdo/field_types.html[JDO docs] for more details on this.
-
-Moreover, these datatypes are _not_ in the default fetch group, meaning that JDO/DataNucleus will perform an additional `SELECT` query for each attribute.
-To avoid this extra query, the annotation should indicate that the property is in the default fetch group.
-
-For example, the `ToDoItem` (in the https://github.com/isisaddons/isis-app-todoapp[todoapp example app] (not ASF)) defines the `dueBy` property as follows:
-
-[source,java]
-----
-@javax.jdo.annotations.Persistent(defaultFetchGroup="true")
-@javax.jdo.annotations.Column(allowsNull="true")
-@Getter @Setter
-private LocalDate dueBy;
-----
-
-
-[[__ugfun_class-structure_properties_datatypes_bigdecimals]]
-=== ``BigDecimal``s (Precision)
-
-Working with `java.math.BigDecimal` properties takes a little care due to scale/precision issues.
-
-For example, suppose we have:
-
-[source,java]
-----
-@lombok.Getter @lombok.Setter
-private BigDecimal impact;
-----
-
-JDO/DataNucleus creates, at least with HSQL, the table with the field type as NUMERIC(19). No decimal digits are admitted. (Further details http://hsqldb.org/doc/2.0/guide/sqlgeneral-chapt.html#sgc_numeric_types[here]).
-
-What this implies is that, when a record is inserted, a log entry similar to this one appears:
-
-[source,java]
-----
-INSERT INTO ENTITY(..., IMPACT, ....) VALUES (...., 0.5, ....)
-----
-
-But when that same record is retrieved, the log will show that a value of "0" is returned, instead of 0.5.
-
-The solution is to explicitly add the scale to the field like this:
-
-[source,java]
-----
-@javax.jdo.annotations.Column(scale=2)
-@lombok.Getter @lombok.Setter
-private BigDecimal impact;
-----
-
-In addition, you should also set the scale of the `BigDecimal`, using `setScale(scale, roundingMode)`.
-
-More information can be found http://www.opentaps.org/docs/index.php/How_to_Use_Java_BigDecimal:_A_Tutorial[here] and http://www.tutorialspoint.com/java/math/bigdecimal_setscale_rm_roundingmode.htm[here].
-
-
-
-[[__ugfun_class-structure_properties_datatypes_blobs]]
-=== ``Blob``s
-
-Apache Isis configures JDO/DataNucleus so that the properties of type `org.apache.isis.applib.value.Blob` and `org.apache.isis.applib.value.Clob` can also be persisted.
-
-As for xref:../ugfun/ugfun.adoc#__ugfun_class-structure_properties_datatypes_joda-dates[Joda dates], this requires the `@javax.jdo.annotations.Persistent` annotation.
-However, whereas for dates one would always expect this value to be retrieved eagerly, for blobs and clobs it is not so clear cut.
-
-For example, in the `ToDoItem` class (of the https://github.com/isisaddons/isis-app-todoapp/blob/0333852ddd18ad67e3356fccf805aa442246790d/dom/src/main/java/todoapp/dom/todoitem/ToDoItem.java#L442[todoapp example app] (non-ASF) the `attachment` property is as follows:
-
-[source,java]
-----
-@javax.jdo.annotations.Persistent(defaultFetchGroup="false", columns = {
-    @javax.jdo.annotations.Column(name = "attachment_name"),
-    @javax.jdo.annotations.Column(name = "attachment_mimetype"),
-    @javax.jdo.annotations.Column(name = "attachment_bytes", jdbcType="BLOB", sqlType = "LONGVARBINARY")
-})
-@Property(
-        optionality = Optionality.OPTIONAL
-)
-@lombok.Getter @lombok.Setter
-private Blob attachment;
-----
-
-The three `@javax.jdo.annotations.Column` annotations are required because the mapping classes that Apache Isis provides (https://github.com/apache/isis/blob/isis-1.4.0/component/objectstore/jdo/jdo-datanucleus/src/main/java/org/apache/isis/objectstore/jdo/datanucleus/valuetypes/IsisBlobMapping.java#L59[IsisBlobMapping] and https://github.com/apache/isis/blob/isis-1.4.0/component/objectstore/jdo/jdo-datanucleus/src/main/java/org/apache/isis/objectstore/jdo/datanucleus/valuetypes/IsisClobMapping.java#L59[IsisClobMapping]) map to 3 columns.
-(It is not an error to omit these `@Column` annotations, but without them the names of the table columns are simply suffixed `_0`, `_1`, `_2` etc.
-
-If the `Blob` is mandatory, then use:
-
-[source,java]
-----
-@javax.jdo.annotations.Persistent(defaultFetchGroup="false", columns = {
-    @javax.jdo.annotations.Column(name = "attachment_name", allowsNull="false"),
-    @javax.jdo.annotations.Column(name = "attachment_mimetype", allowsNull="false"),
-    @javax.jdo.annotations.Column(name = "attachment_bytes",
-                                  jdbcType="BLOB", sqlType = "LONGVARBINARY",
-                                  allowsNull="false")
-})
-@Property(
-    optionality = Optionality.MANDATORY
-)
-@lombok.Getter @lombok.Setter
-private Blob attachment;
-----
-
-[NOTE]
-====
-If specifying a `sqlType` of "LONGVARBINARY" does not work, try instead "BLOB".
-There can be differences in behaviour between JDBC drivers.
-====
-
-[[__ugfun_class-structure_properties_datatypes_clobs]]
-=== ``Clob``s
-
-
-Mapping `Clob`s works in a very similar way to xref:../ugfun/ugfun.adoc#__ugfun_class-structure_properties_datatypes_blobs[``Blob``]s, but the `jdbcType` and `sqlType` attributes will, respectively, be `CLOB` and `LONGVARCHAR`:
-
-[source,java]
-----
-@javax.jdo.annotations.Persistent(defaultFetchGroup="false", columns = {
-    @javax.jdo.annotations.Column(name = "attachment_name"),
-    @javax.jdo.annotations.Column(name = "attachment_mimetype"),
-    @javax.jdo.annotations.Column(name = "attachment_chars",
-                                  jdbcType="CLOB", sqlType = "LONGVARCHAR")
-})
-private Clob doc;
-@Property(
-    optionality = Optionality.OPTIONAL
-)
-public Clob getDoc() {
-    return doc;
-}
-public void setDoc(final Clob doc) {
-    this.doc = doc;
-}
-----
-
-[NOTE]
-====
-If specifying a `sqlType` of "LONGVARCHAR" does not work, try instead "CLOB".  There can be differences in behaviour between JDBC drivers.
-====
-
-
-[[__ugfun_class-structure_properties_datatypes_mapping-to-varbinary-or-varchar]]
-=== Mapping to VARBINARY or VARCHAR
-
-Instead of mapping to a sqlType of `LONGVARBINARY` (or perhaps `BLOB`), you might instead decide to map to a `VARBINARY`.
-The difference is whether the binary data is held "on-row" or as a pointer "off-row"; with a `VARBINARY` the data is held on-row and so you will need to specify a length.
-
-For example:
-
-[source,java]
-----
-@javax.jdo.annotations.Column(name = "attachment_bytes", jdbcTypr="BLOB", sqlType = "VARBINARY", length=2048)
-----
-
-The same argument applies to `LONGVARCHAR` (or `CLOB`); you could instead map to a regular `VARCHAR`:
-
-[source,java]
-----
-@javax.jdo.annotations.Column(name = "attachment_chars", sqlType = "VARCHAR", length=2048)
-----
-Support and maximum allowed length will vary by database vendor.
-
-
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts.adoc
index e9819a0..f7bc062 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts.adoc
@@ -12,12 +12,8 @@ We've also added some new insights and made sure the material we've used is rele
 
 include::_ugfun_core-concepts_philosophy.adoc[leveloffset=+1]
 include::_ugfun_core-concepts_principles.adoc[leveloffset=+1]
-
 include::_ugfun_core-concepts_apache-isis-vs.adoc[leveloffset=+1]
 
-include::_ugfun_core-concepts_building-blocks.adoc[leveloffset=+1]
-include::_ugfun_core-concepts_framework-provided-services.adoc[leveloffset=+1]
-include::_ugfun_core-concepts_add-ons.adoc[leveloffset=+1]
-include::_ugfun_core-concepts_other-deployment-options.adoc[leveloffset=+1]
+include::_ugfun_core-concepts_deployment-options.adoc[leveloffset=+1]
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_add-ons.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_add-ons.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_add-ons.adoc
deleted file mode 100644
index c13a4b2..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_add-ons.adoc
+++ /dev/null
@@ -1,54 +0,0 @@
-[[_ugfun_core-concepts_add-ons]]
-= Isis Add-ons & Incode Catalog
-: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/
-
-
-The link:http://www.isisaddons.org[Isis Addons] website provides a number of reusable modules for Apache Isis, focusing either on specific technologies or in technical cross-cutting concerns.
-Some of these modules implement SPIs defined by the framework.
-
-The link:http://catalog.incode.org[Incode Catalog] website also provides a number of reusable modules, focusing on business logic for generic subdomains.
-
-This section surveys the functionality available.
-
-
-[WARNING]
-====
-Note that Isis Addons and Incode Catalog, although maintained by Apache Isis committers, are not part of the ASF.
-====
-
-
-
-The modules themselves fall into a number of broader groups:
-
-* modules that provide an implementations of SPI defined by Apache Isis +
-+
-where Apache Isis has hooks to use the service if defined by provides no implementations of its own. +
-+
-From the link:http://www.isisaddons.org[Isis Addons] website, the http://github.com/isisaddons/isis-module-command[command], http://github.com/isisaddons/isis-module-audit[auditer], http://github.com/isisaddons/isis-module-publishmq[publisher], http://github.com/isisaddons/isis-module-security[security]  and http://github.com/isisaddons/isis-module-sessionlogger[sessionlogger] modules fall into this category.  Typically the domain objects themselves wouldn't interact with these services
-
-* modules that provide standalone domain services with their own API and implementation +
-+
-These are simply intended to be used by domain objects. +
-+
-From the link:http://www.isisaddons.org[Isis Addons] website, the http://github.com/isisaddons/isis-module-docx[docx], http://github.com/isisaddons/isis-module-excel[excel], http://github.com/isisaddons/isis-module-freemarker[freemarker], http://github.com/isisaddons/isis-module-pdfbox[pdfbox], http://github.com/isisaddons/isis-module-settings[settings], http://github.com/isisaddons/isis-module-servletapi[servletapi], http://github.com/isisaddons/isis-module-stringinterpolator[stringinterpolator] and http://github.com/isisaddons/isis-module-xdocreport[xdocreport] fall into this category. +
-+
-From the link:http://catalog.incode.org[Incode Catalog] website, the http://github.com/incodehq/incode-module-alias[alias], http://github.com/incodehq/incode-module-classification[classification], http://github.com/incodehq/incode-module-commchannel[commchannel], http://github.com/incodehq/incode-module-communications[communications], http://github.com/incodehq/incode-module-country[country], http://github.com/incodehq/incode-module-docfragment[docfragment],
-http://github.com/incodehq/incode-module-document[document] and http://github.com/incodehq/incode-module-document[note] modules fall into this category.
-
-* modules that provide standalone domain entities (and supporting services) for a particular subdomain +
-+
-From the link:http://www.isisaddons.org[Isis Addons] website, the http://github.com/isisaddons/isis-module-tags[tags] module falls into this category
-
-* modules that provide developer/testing utilities +
-+
-From the link:http://www.isisaddons.org[Isis Addons] website, the http://github.com/isisaddons/isis-module-fakedata[fakedata] module provides fakedata for unit- and integration testing +
-+
-From the link:http://catalog.incode.org[Incode Catalog] website, the http://github.com/incodehq/incode-module-fixturesupport[fixturesupport], http://github.com/incodehq/incode-module-integtestsupport[integtestsupport] and http://github.com/incodehq/incode-module-unittestsupport[unittestsupport] modules fall into this category.
-
-* modules that support runtime/integration support +
-+
-From the link:http://www.isisaddons.org[Isis Addons] website, link:http://github.com/isisaddons/isis-module-flywaydb[flywaydb] handle RDBMS schema migration, http://github.com/isisaddons/isis-module-quartz[quartz] provides scheduling of background jobs; and the http://github.com/isisaddons/isis-module-togglz[togglz] provides feature toggles.
-
-Each of the modules has a full README and demo application demonstrating their usage.  The sections below briefly outline the capabilities of these modules.

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs.adoc
index 8dea746..9bc1a6e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs.adoc
@@ -7,7 +7,7 @@
 Many other frameworks promise rapid application development and provide automatically generated user interfaces, so how do they compare to Apache Isis?
 
 
-include::_ugfun_core-concepts_apache-isis-vs_mvc-server-side-frameworks.adoc[leveloffset=+1]
+include::_ugfun_core-concepts_apache-isis-vs_mvc-server-side.adoc[leveloffset=+1]
 include::_ugfun_core-concepts_apache-isis-vs_cqrs.adoc[leveloffset=+1]
 include::_ugfun_core-concepts_apache-isis-vs_event-sourcing.adoc[leveloffset=+1]
 include::_ugfun_core-concepts_apache-isis-vs_metawidget.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_mvc-server-side-frameworks.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_mvc-server-side-frameworks.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_mvc-server-side-frameworks.adoc
deleted file mode 100644
index b806289..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_mvc-server-side-frameworks.adoc
+++ /dev/null
@@ -1,29 +0,0 @@
-[[_ugfun_core-concepts_apache-isis-vs_mvc-server-side-frameworks]]
-= vs MVC server-side frameworks
-: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/
-
-
-
-Some of most commonly used frameworks today are link:http://www.spring.io/[Spring MVC], link:http://rubyonrails.org/[Ruby on Rails] and link:http://www.grails.org[Grails], all of which implement one flavour or another of the server-side MVC pattern.
-The MVC 1.0 specification (originally scheduled for JavaEE 8 though since removed) is also similar.
-
-These frameworks all use the classic  *model-view-controller* ( _MVC_) pattern for web applications, with scaffolding, code-generation, and/or metaprogramming tools for the controllers and views, as well as convention over configuration to define how these components interact.
-The views provided out of the box by these frameworks tend to be simple  _CRUD_-style interfaces.
-More sophisticated behavior is accomplished by customizing the generated controllers.
-
-The most obvious difference when developing an Apache Isis application is its deliberate lack of an explicit controller layer; non- _CRUD_ behavior is automatically made available in its generic object-oriented  _UI_s.
-More sophisticated UIs can be built either by xref:../ugvw/ugvw.adoc#_ugvw_extending[extending Apache Isis' Wicket viewer] or by writing a bespoke UI leveraging the REST (hypermedia) API automatically exposed by xref:../ugvro/ugvro.adoc#[Isis' Restful Objects viewer].
-Other frameworks can also be used to implement REST APIs, of course, but generally they require a significant amount of development to get anywhere near the level of sophistication provided automatically by Apache Isis' REST API.
-
-Although these frameworks all provide their own ecosystems of extensions, Apache Isis' equivalent link:http://www.isisaddons.org[Isis Addons] (non-ASF) tend to work at a higher-level of abstraction.
-For example, each of these frameworks will integrate with various security mechanism, but the http://github.com/isisaddons/isis-module-security[Isis addons' security module] provides a full subdomain of users, roles, features and permissions that can be plugged into any Isis application.
-Similarly, the http://github.com/isisaddons/isis-module-command[Isis addons' command] and http://github.com/isisaddons/isis-module-audit[Isis addons' audit] modules in combination provide a support for auditing and traceability that can also be used for out of the box profiling.
-Again, these addons can be plugged into any Isis app.
-
-In terms of testing support, each of these other frameworks provide mechanisms to allow the webapp to be tested from within a JUnit test harness.
-Apache Isis' support is similar.
-Where Apache Isis differs though is that it enables end-to-end testing without the need for slow and fragile Selenium tests.
-Instead, Apache Isis provides a "xref:../ugtst/ugtst.adoc#_ugtst_integ-test-support_wrapper-factory[WrapperFactory]" domain service that allows the generic UI provided to in essence be simulated.
-On a more pragmatic level, the http://github.com/isisaddons/isis-module-fakedata[Isis addons' fakedata] module does "what it says on the tin", allowing both unit- and integration-tests to focus on the salient data and fake out the rest.

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_mvc-server-side.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_mvc-server-side.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_mvc-server-side.adoc
new file mode 100644
index 0000000..ae4f1b6
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_mvc-server-side.adoc
@@ -0,0 +1,29 @@
+[[_ugfun_core-concepts_apache-isis-vs_mvc-server-side]]
+= vs MVC server-side
+: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/
+
+
+
+Some of most commonly used frameworks today are link:http://www.spring.io/[Spring MVC], link:http://rubyonrails.org/[Ruby on Rails] and link:http://www.grails.org[Grails], all of which implement one flavour or another of the server-side MVC pattern.
+The MVC 1.0 specification (originally scheduled for JavaEE 8 though since removed) is also similar.
+
+These frameworks all use the classic  *model-view-controller* ( _MVC_) pattern for web applications, with scaffolding, code-generation, and/or metaprogramming tools for the controllers and views, as well as convention over configuration to define how these components interact.
+The views provided out of the box by these frameworks tend to be simple  _CRUD_-style interfaces.
+More sophisticated behavior is accomplished by customizing the generated controllers.
+
+The most obvious difference when developing an Apache Isis application is its deliberate lack of an explicit controller layer; non- _CRUD_ behavior is automatically made available in its generic object-oriented  _UI_s.
+More sophisticated UIs can be built either by xref:../ugvw/ugvw.adoc#_ugvw_extending[extending Apache Isis' Wicket viewer] or by writing a bespoke UI leveraging the REST (hypermedia) API automatically exposed by xref:../ugvro/ugvro.adoc#[Isis' Restful Objects viewer].
+Other frameworks can also be used to implement REST APIs, of course, but generally they require a significant amount of development to get anywhere near the level of sophistication provided automatically by Apache Isis' REST API.
+
+Although these frameworks all provide their own ecosystems of extensions, Apache Isis' equivalent link:http://www.isisaddons.org[Isis Addons] (non-ASF) tend to work at a higher-level of abstraction.
+For example, each of these frameworks will integrate with various security mechanism, but the http://github.com/isisaddons/isis-module-security[Isis addons' security module] provides a full subdomain of users, roles, features and permissions that can be plugged into any Isis application.
+Similarly, the http://github.com/isisaddons/isis-module-command[Isis addons' command] and http://github.com/isisaddons/isis-module-audit[Isis addons' audit] modules in combination provide a support for auditing and traceability that can also be used for out of the box profiling.
+Again, these addons can be plugged into any Isis app.
+
+In terms of testing support, each of these other frameworks provide mechanisms to allow the webapp to be tested from within a JUnit test harness.
+Apache Isis' support is similar.
+Where Apache Isis differs though is that it enables end-to-end testing without the need for slow and fragile Selenium tests.
+Instead, Apache Isis provides a "xref:../ugtst/ugtst.adoc#_ugtst_integ-test-support_wrapper-factory[WrapperFactory]" domain service that allows the generic UI provided to in essence be simulated.
+On a more pragmatic level, the http://github.com/isisaddons/isis-module-fakedata[Isis addons' fakedata] module does "what it says on the tin", allowing both unit- and integration-tests to focus on the salient data and fake out the rest.

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_building-blocks.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_building-blocks.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_building-blocks.adoc
deleted file mode 100644
index fb106f2..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_building-blocks.adoc
+++ /dev/null
@@ -1,314 +0,0 @@
-[[_ugfun_core-concepts_building-blocks]]
-= Building Blocks
-: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/
-
-In this section we run through the main building blocks that make up an Apache Isis application.
-
-[[__ugfun_core-concepts_building-blocks_metamodel]]
-== A MetaModel
-
-At its core, Apache Isis is a metamodel that is built at runtime from the domain classes (eg `Customer.java`), along with optional supporting metadata (eg `Customer.layout.xml`).
-
-The contents of this metamodel is inferred from the Java classes discovered on the classpath: the entities and supporting services, as well the members of those classes.
-The detail of the metamodel is generally explicit, usually represented by Java annotations such as `@Title` or `@Action`.
-Notably the metamodel is xref:../ugbtb/ugbtb.adoc#_ugbtb_programming-model[extensible]; it is possible to teach Apache Isis new programming conventions/rules (and conversely to remove those that are built in).
-
-Most of the annotations recognized by the framework are defined by the Apache Isis framework itself.
-For example the `@Title` annotation -- which identifies how the framework should derive a human-readable label for each rendered domain object -- is part of the `org.apache.isis.applib.annotations` package.
-However the framework also recognizes certain other JEE annotations such as `@javax.inject.Inject` (used for dependency injection).
-
-The framework uses DataNucleus for its persistence mechanism.
-This is an ORM that implements the JDO and JPA APIs, and which can map domain objects either to an RDBMS or to various NoSQL objectstores such as MongoDB or Neo4J.
-Apache Isis recognizes a number of the JDO annotations such as `@javax.jdo.annotations.Column(allowsNull=...)`.
-
-In addition, the framework builds up the metamodel for each domain object using
-xref:../ugvw/ugvw.adoc#_ugvw_layout[layout hints], such as `Customer.layout.xml`.
-These provide metadata such as grouping elements of the UI together, using multi-column layouts, and so on.
-The layout file can be modified while the application is still running, and are picked up automatically; a useful way to speed up feedback.
-
-[TIP]
-====
-At the time of writing Apache Isis only recognizes and supports the JDO API, though we expect JPA to be supported in the future.
-====
-
-
-
-[[__ugfun_core-concepts_building-blocks_types-of-domain-objects]]
-== Type of Domain Objects
-
-Most domain objects that the end-user interacts with are *domain entities*, such as `Customer`, `Order`, `Product` and so on.
-These are persistent objects and which are mapped to a database (usually relational), using JDO/DataNucleus annotations.
-From the end-user's perspective the UI displays a single domain object per page; they can then inspect and modify its state, and navigate to related objects.
-
-The next type of domain object to discuss is *domain services*.
-These are (usually) singleton stateless services that provide additional functionality.
-The behaviour of these services is rendered in various ways, though the most obvious is as the menu actions on the top-level menu bars in the xref:../ugvw/ugvw.adoc#[Wicket viewer]'s UI.
-
-Domain objects can also delegate to domain services; domain services are automatically injected into every other domain object; this includes domain entities as well as other services.
-This injection of domain services into entities is significant: it allows business logic to be implemented in the domain entities, rather than have it "leach away" into
-supporting service layers.
-Said another way: it is the means by which Apache Isis helps you avoid the anaemic domain model anti-pattern.
-
-As well as domain entities -- mapped to a datastore -- Apache Isis also supports *view models*.
-End users interact with view models in the same way as a domain entity, indeed they are unlikely to distinguish one from the other.
-However view models are _not_ mapped to the underlying database, rather they represent some aggregation of state from one or more underlying entities.
-Their state is serialized and recreated from their internal identifier; this identifier is visible as the object's URL in the xref:../ugvw/ugvw.adoc#[Wicket viewer] or xref:../ugvro/ugvro.adoc#[RestfulObjects viewer].
-
-There's no need though for the view model to aggregate the state of regular domain entities.
-A view model could also be used as a proxy for some externally managed entity, accessed over a web service or REST API; it could even be a representation of state held in-memory (such as user preferences, for example).
-
-There are also several types of domain services.
-Most easily described are those domain services (discussed above) that are represented as the menu actions on top-level menu bars.
-Another variation are *contributed services*: domain services that contribute behaviour or (derived) state to entities/view models.
-Finally domain services may also simply provide additional non-UI functionality; an example being to perform an address geocoding lookup against the google-maps API.
-
-Also worth mentioning: domain services can also be either singletons (discussed above) or request-scoped; the latter being annotated with `@javax.enterprise.context.RequestScoped`.
-An example of the request-scoped service is the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_Scratchpad[`Scratchpad`] service, for sharing arbitrary data between multiple objects.
-
-The final type of domain object is the *mixin*.
-These are similar to contributed services in that they also contribute (or rather, mixin) both behaviour or (derived) state to entities/view models.
-However, they provide a more control over contributed services, with a cleaner programming model similar to traits found in other languages.
-
-The diagram below summarizes the various types of domain object:
-
-image::{_imagesdir}core-concepts/building-blocks/types-of-domain-object.png[width="860px",link="{_imagesdir}core-concepts/building-blocks/types-of-domain-object.png"]
-
-
-The Apache Isis programming model uses annotations to distinguish these object types:
-
-* *view models* are annotated either with `@DomainObject(nature=VIEW_MODEL)` or using `@ViewModel`.
-Which is used is a matter of personal preference.  +
-+
-It is also possible to implement the `ViewModel` interface, for finer-grained control.
-
-* *domain entities* that are persisted to the database (as the vast majority will) are annotated with `@DomainObject(nature=ENTITY)`.
-In addition such domain entities are annotated with the JDO/DataNucleus annotation of
-`@javax.jdo.annotations.PersistenceCapable`. +
-+
-In addition, if a domain entity is a proxy for state managed in an external system, or merely for some state held in-memory, then `@DomainObject(nature=EXTERNAL_ENTITY)` or `@DomainObject(nature=INMEMORY_ENTITY)` can be used.
-
-* *mixins* are annotated either with `@DomainObject(nature=MIXIN)` or using `@Mixin`.
-As for view models, which is used is a matter of personal preference.
-
-* finally, *domain services*` are annotated with `@DomainService(nature=...)` where the nature is either `VIEW_MENU_ONLY` (for domain services whose actions appear on the top-level menu bars), or `VIEW_CONTRIBUTIONS_ONLY` (for domain services whose actions are contributed to entities or view models), or `DOMAIN` (for domain services whose
-functionality is simply for other domain objects to invoke programmatically).
-+
-It is also possible to specify a nature of simply `VIEW`, this combining `VIEW_MENU_ONLY` and `VIEW_CONTRIBUTIONS_ONLY`.
-This is in fact the default, useful for initial prototyping.
-A final nature is `VIEW_REST_ONLY` which is for domain services whose functionality is surfaced only by the xref:../ugvro/ugvro.adoc#[RestfulObjects viewer].
-
-Worth emphasising is that domain entities and view models hold state, whereas domain services are generally stateless.
-If a domain service does hold state (eg the `Scratchpad` service noted above) then it should be `@RequestScoped` so that this state is short-lived and usable only within a single request.
-
-
-
-[[__ugfun_core-concepts_building-blocks_objects-members]]
-== Object Members
-
-Every domain object in Apache Isis consists of (at most) three types of members:
-
-* properties, such as a ``Customer``'s `firstName`
-
-* collections, such as a ``Customer``'s `orders` collection of ``Order``s
-
-* actions, such as a ``Customer'``s `placeOrder(...)` method.
-
-Some domain objects -- specifically domain services and mixins -- only have actions.
-In the case of contributing services and mixins these actions can (depending upon their semantics and signatures) be represented as derived properties or collections on the entity/view model to which they contribute/mix-in.
-
-
-=== Properties
-
-Properties follow the standard getter/setter pattern, with the return type being a scalar (a value object or another entity or view model).
-
-For example, with:
-
-[source,java]
-----
-public class Customer
-    private String firstName;
-    public String getFirstName() { return firstName; }
-    public void setFirstName(String firstName) { this.firstName = firstName; }
-    ...
-}
-----
-
-the framework infers the `Customer` domain entity, which in turn has a `firstName` string _property_.
-
-
-=== Collections
-
-Collections are also represented by a getter and setter, however the return type is a `Collection` or subtype.
-
-For example, with:
-
-[source,java]
-----
-public class Customer
-    private SortedSet<Order> orders = new TreeSet<Order>();
-    public SortedSet<Order> getOrders() { return orders; }
-    public void setOrders(SortedSet<Order> orders) { this.orders = orders; }
-    ...
-}
-----
-
-the framework infers the `orders` _collection_.
-
-[TIP]
-====
-The most commonly used collection type is `java.util.SortedSet`; entities are most commonly mapped to a relational database (ie a datastore with set semantics) and we recommend that all entities define a natural ordering so that when rendered in the UI they will be ordered "meaningfully" to the end-user.
-====
-
-
-=== Actions
-
-The third type of object member is actions.
-(To a first approximation), actions are all public methods that do not represent properties or collections.
-
-For example:
-
-[source,java]
-----
-public class Customer
-    public Customer placeOrder(Product p, int quantity) { ... }
-    ...
-}
-----
-
-corresponds to the `placeOrder` _action_.
-
-[NOTE]
-====
-The above _is_ a simplification; the Apache Isis programming model also recognizes a number of other supporting methods each of which has its own prefix such as `hide`, `disable` or `validate`.
-These can be considered as "reserved words" in Apache Isis, and do _not_ correspond to actions even though they have public visibility.
-====
-
-
-
-== Entities vs View Models
-
-When developing an Apache Isis application you will most likely start off with the persistent domain entities: `Customer`, `Order`, `Product`, and so on.
-For some applications this may well suffice.
-However, if the application needs to integrate with other systems, or if the application needs to support reasonably complex business processes, then you may need to look beyond just domain entities.
-
-To support these use cases we support view models.
-In the same way that an (RDBMS) database view can aggregate and abstract from multiple underlying database tables, so a view model sits on top of one or many underlying entities.
-
-View models are not persisted, but nevertheless they can have behaviour (and titles, and icons) just like domain entities.
-Indeed, to a user of the system there is no particular distinction (again, in the same way that when using an RDBMS one can use database views and database tables pretty much interchangeably).
-
-View models generally tend to be associated with supporting a particular use case; logically they are part of the application layer, not part of the domain layer (where entities live).
-
-We introduce view models here because they do get mentioned quite often within the users and reference guide.
-However, we do consider them a more advanced topic; we generally recommend that you build your applications from the domain layer up, rather than from the view model down.
-
-For further discussion on view models, see xref:../ugbtb/ugbtb.adoc#_ugbtb_view-models[this topic].
-
-
-
-
-[[__ugfun_core-concepts_building-blocks_domain-services]]
-== Domain Services
-
-Domain services consist of a set of logically grouped actions, and as such follow the same conventions as for entities.
-However, a service cannot have (persisted) properties, nor can it have (persisted) collections.
-
-Domain services are instantiated once and once only by the framework, and are used to centralize any domain logic that does not logically belong in a domain entity or value.
-Apache Isis will automatically inject services into every domain entity that requests them, and into each other.
-
-For convenience you can inherit from AbstractService or one of its subclasses, but this is not mandatory.
-
-
-=== Domain Services vs View Services
-
-NOTE: FIXME
-
-`@DomainService(nature=...)`
-
-.Factories, Repositories and Services
-****
-A distinction is sometimes made between a factory (that creates object) and a repository (that is used to find existing objects).
-You will find them discussed separately in Evans' link:http://books.google.com/books/about/Domain_Driven_Design.html?id=hHBf4YxMnWMC[Domain Driven Design], for example.
-
-In Apache Isis these are all implemented as domain services.
-Indeed, it is quite common to have a domain service that acts as both a factory and a repository.
-****
-
-
-
-[[__ugfun_core-concepts_building-blocks_mixins-and-contributions]]
-== Mixins & Contributions
-
-NOTE: FIXME
-
-
-For more information, see xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_contributions[this topic on contribution]s, and xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_mixins[this topic on mixin]s.
-
-
-
-[[__ugfun_core-concepts_building-blocks_domain-events]]
-== Domain Events
-
-NOTE: FIXME; see xref:../rgcms/rgcms.adoc#_rgcms_classes_domainevent[domain event] classes.
-
-
-
-=== UI Events
-
-NOTE: FIXME; see xref:../rgcms/rgcms.adoc#_rgcms_classes_uievent[UI event] classes.
-
-
-
-
-[[__ugfun_core-concepts_building-blocks_oid]]
-== OIDs
-
-As well as defining a xref:../ugfun/ugfun.adoc#__ugfun_core-concepts_building-blocks_metamodel[metamodel] of the structure (domain classes) of its domain objects, Apache Isis also manages the runtime instances of said domain objects.
-
-When a domain entity is recreated from the database, the framework keeps track of its identity through an "OID": an object identifier.
-Fundamentally this is a combination of its type (domain class), along with an identifier.
-You can think of it as its "primary key", except across all domain entity types.
-
-For portability and resilience, though, the object type is generally an alias for the actual domain class: thus "customers.CUS", say, rather than "com.mycompany.myapp.customers.Customer".
-This is derived from an annotation.
-The identifier meanwhile is always converted to a string.
-
-Although simple, the OID is an enormously powerful concept: it represents a URI to any domain object managed by a given Apache Isis application.
-With it, we have the ability to lookup any arbitrary domain objects.
-
-Some examples:
-
-* an OID allows sharing of information between users, eg as a deep link to be pasted into an email.
-
-* the information within an OID could be converted into a barcode, and stamped onto a PDF form.
-When the PDF is scanned by the mail room, the barcode could be read to attach the correspondence to the relevant domain object.
-
-* as a handle to any object in an audit record, as used by xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditerService`] or xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`] (the latter deprecated);
-
-* similarly within implementations of xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] to persist `Command`
-objects
-
-* similarly within implementations of xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`]
-to persist published action invocations
-
-* and of course both the xref:../ugvro/ugvro.adoc#[RestfulObjects viewer] and
-xref:../ugvw/ugvw.adoc#[Wicket viewer]
-use the oid tuple to look up, render and allow the user to interact with domain objects.
-
-Although the exact content of an OID should be considered opaque by domain objects, it is possible for domain objects to obtain OIDs.
-These are represented as `Bookmark`s, obtained from the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`].
-Deep links meanwhile can be obtained from the xref:../rgant/rgant.adoc#_rgant-DeepLinkService[`@DeepLinkService`].
-
-OIDs can also be converted into XML format, useful for integration scenarios.
-The xref:../rgcms/rgcms.adoc#_rgcms_schema-common[common schema] XSD defines the `oidDto` complex type for precisely this purpose.
-
-
-
-[[__ugfun_core-concepts_building-blocks_value-objects]]
-== Value Objects (Primitives)
-
-NOTE: FIXME
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_deployment-options.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_deployment-options.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_deployment-options.adoc
new file mode 100644
index 0000000..82ea368
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_deployment-options.adoc
@@ -0,0 +1,93 @@
+[[_ugfun_core-concepts_deployment-options]]
+= Deployment Options
+: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 is a mature platform suitable for production deployment, with its "sweet spot" being line-of-business enterprise applications.
+So if you're looking to develop that sort of application, we certainly hope you'll seriously evaluate it.
+
+But there are other ways that you can make Apache Isis work for you; in this section we explore a few of them.
+
+
+
+== Deploy to production
+
+Let's start though with the default use case for Apache Isis: building line-of-business enterprise applications, on top of its Wicket viewer.
+
+Apache Wicket, and therefore Apache Isis in this configuration, is a stateful architecture.
+As a platform it is certainly capable of supporting user bases of several thousand (with perhaps one or two hundred concurrent); however it isn't an architecture that you should try to scale up to tens of thousands of concurrent users.
+
+The UI generated by the Wicket viewer is well suited to many line-of-business apps, but it's also worth knowing that (with a little knowledge of the Wicket APIs) it relatively straightforward to extend.
+As described in xref:../ugfun/ugfun.adoc#_ugfun_available-domain-services_isis-addons[Isis addons] chapter, the viewer already has integrations with https://github.com/isisaddons/isis-wicket-gmap3[google maps], https://github.com/isisaddons/isis-wicket-fullcalendar2[a full calendar] and an https://github.com/isisaddons/isis-wicket-excel[export to Excel] component.
+We are also aware of integrations with SVG images (for floor maps of shopping center) and of custom widgets displaying a catalogue (text and images) of medical diseases.
+
+Deploying on Apache Isis means that the framework also manages object persistence.
+For many line-of-business applications this will mean using a relational database.
+It is also possible (courtesy of its integratinon with link:http://www.datanucleus.org[DataNucleus]) to deploy an Isis app to a NoSQL store such as Neo4J or MongoDB; and it is also possible to deploy to cloud platforms such as link:https://cloud.google.com/appengine/docs[Google App Engine (GAE)].
+
+
+
+== Prototyping
+
+Even if you don't intend to deploy your application on top of Apache Isis, there can be a lot of value in using Apache Isis for prototyping.
+Because all you need do to get an app running is write domain objects, you can very quickly explore a domain object model and validate ideas with a domain expert.
+
+By focusing just on the domain, you'll also find that you start to develop a ubiquitous language - a set of terms and concepts that the entire team (business and technologists alike) have a shared understanding.
+
+Once you've sketched out your domain model, you can then "start-over" using your preferred platform.
+
+
+
+
+
+== Deploy on your own platform
+
+The programming model defined by Apache Isis deliberately minimizes the dependencies on the rest of the framework.
+In fact, the only hard dependency that the domain model classes have on Apache Isis is through the `org.apache.isis.applib` classes, mostly to pick up annotations such as `@Disabled`.
+So, if you have used Apache Isis for prototyping (discussed above), then note that it's quite feasible to take your domain model a the basis of your actual development effort; Apache Isis' annotations and programming conventions will help ensure that any subtle semantics you might have captured in your prototyping are not lost.
+
+If you go this route, your deployment platform will of course need to provide similar capabilities to Apache Isis.
+In particular, you'll need to figure out a way to inject domain services into domain entities (eg using a JPA listener), and you'll also need to reimplement any domain services you have used that Apache Isis provides "out-of-the-box" (eg xref:../rgsvc/rgsvc.adoc#_rgsvc_api_QueryResultsCache[`QueryResultsCache`] domain service).
+
+
+
+
+
+== Deploy the REST API
+
+REST (Representation State Transfer) is an architectural style for building highly scalable distributed systems, using the same principles as the World Wide Web.
+Many commercial web APIs (twitter, facebook, Amazon) are implemented as either pure REST APIs or some approximation therein.
+
+The http://restfulobjects.org[Restful Objects specification] defines a means by a domain object model can be exposed as RESTful resources using JSON representations over HTTP.
+Apache Isis' xref:../ugvro/ugvro.adoc#[RestfulObjects viewer] is an implementation of that spec, making any Apache Isis domain object automatically available via REST.
+
+There are a number of use cases for deploying Isis as a REST API, including:
+
+* to allow a custom UI to be built against the RESTful API +
++
+For example, using Angular or some other RIA technology such as Flex, JavaFX, Silverlight
+
+* to enable integration between systems +
++
+REST is designed to be machine-readable, and so is an excellent choice for synchronous data interchange scenarios.
+
+* as a ready-made API for migrating data from one legacy system to its replacement.
+
+As for the auto-generated webapps, the framework manages object persistence.
+It is perfectly possible to deploy the REST API alongside an auto-generated webapp; both work from the same domain object model.
+
+
+
+
+
+== Implement your own viewer
+
+Isis' architecture was always designed to support multiple viewers; and indeed Apache Isis out-of-the-box supports two: the Wicket viewer, and the Restful Objects viewer (or three, if one includes the Wrapper Factory).
+
+While we mustn't understate the effort involved here, it is feasible to implement your own viewers too.
+Indeed, one of Apache Isis' committers does indeed have a (closed source) viewer, based on http://www.wavemaker.com/[Wavemaker].
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_framework-provided-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_framework-provided-services.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_framework-provided-services.adoc
deleted file mode 100644
index 3eeaac0..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_framework-provided-services.adoc
+++ /dev/null
@@ -1,107 +0,0 @@
-[[_ugfun_core-concepts_framework-provided-services]]
-= Framework-provided Services
-: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/
-
-
-Most framework domain services are API: they exist to provide support functionality to the application's domain objects and services.
-In this case an implementation of the service will be available, either by Apache Isis itself or by Isis Addons (non ASF).
-
-Some framework domain services are SPI: they exist primarily so that the application can influence the framework's behaviour.
-In these cases there is (usually) no default implementation; it is up to the application to provide an implementation.
-
-
-General purpose:
-
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`]; mostly deprecated, replaced by:
-** xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ClockService[`ClockService`]
-** xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ConfigurationService[`ConfigurationService`]
-** xref:../rgsvc/rgsvc.adoc#_rgsvc_api_MessageService[`MessageService`]
-** xref:../rgsvc/rgsvc.adoc#_rgsvc_api_RepositoryService[`RepositoryService`]
-** xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ServiceRegistry[`ServiceRegistry`]
-** xref:../rgsvc/rgsvc.adoc#_rgsvc_api_TitleService[`TitleService`]
-** xref:../rgsvc/rgsvc.adoc#_rgsvc_api_UserService[`UserService`]
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_IsisJdoSupport[`IsisJdoSupport`]
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`]
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`]
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EmailService[`EmailService`]
-
-Commands/Interactions/Background/Auditing/Publishing/Profiling:
-
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`] (SPI)
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] (SPI)
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] (SPI)
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`] (SPI) (deprecated)
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditerService`] (SPI)
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BackgroundService[`BackgroundService`]
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[`BackgroundCommandService`] (SPI)
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`] (SPI) (deprecated)
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublisherService[`PublishererService`] (SPI)
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_MetricsService[`MetricsService`]
-
-
-Information Sharing:
-
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_Scratchpad[`Scratchpad`]
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ActionInvocationContext[`ActionInvocationContext`]
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_QueryResultsCache[`QueryResultsCache`]
-
-UserManagement:
-
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UserProfileService[`UserProfileService`] (SPI)
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UserRegistrationService[`UserRegistrationService`] (SPI)
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_EmailNotificationService[`EmailNotificationService`] (SPI)
-
-Bookmarks and Mementos:
-
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`]
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_MementoService[`MementoService`]
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DeepLinkService[`DeepLinkService`]
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_JaxbService[`JaxbService`]
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_XmlSnapshotService[`XmlSnapshotService`]
-
-Layout and UI Management:
-
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_GridLoaderService[`GridLoaderService`] (SPI)
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_GridService[`GridService`] (SPI)
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_GridSystemService[`GridSystemService`] (SPI)
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_HomePageProviderService[`HomePageProviderService`]
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_HintStore[`HintStore`] (SPI)
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_LayoutService[`LayoutService`]
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_RoutingService[`RoutingService`] (SPI)
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UrlEncodingService[`UrlEncodingService`] (SPI)
-
-REST Support:
-
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_AcceptHeaderService[`AcceptHeaderService`]
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_SwaggerService[`SwaggerService`]
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`] (SPI)
-
-Metamodel:
-
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ApplicationFeatureRepository[`ApplicationFeatureRepository`]
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_MetamodelService[`MetamodelService`]
-
-Other API:
-
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_FixtureScriptsDefault[`FixtureScriptsDefault`]
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_GuiceBeanProvider[`GuiceBeanProvider`]
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_SudoService[`SudoService`]
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_TransactionService[`TransactionService`]
-
-Other SPI:
-
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ClassDiscoveryService[`ClassDiscoveryService`] (SPI)
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ErrorReportingService[`ErrorReportingService`] (SPI)
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_EventSerializer[`EventSerializer`] (SPI)
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ExceptionRecognizer[`ExceptionRecognizer`] (SPI)
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_FixtureScriptsSpecificationProvider[`FixtureScriptsSpecificationProvider`] (SPI)
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_LocaleProvider[`LocaleProvider`] (SPI)
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_TranslationService[`TranslationService`] (SPI)
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_TranslationsResolver[`TranslationsResolver`] (SPI)
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_TranslationsResolver[`TranslationsResolver`] (SPI)
-
-
-A full list of services can be found in the xref:../rgsvc/rgsvc.adoc#_rgsvc[Domain Services] reference guide.
-

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_other-deployment-options.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_other-deployment-options.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_other-deployment-options.adoc
deleted file mode 100644
index 049b883..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_other-deployment-options.adoc
+++ /dev/null
@@ -1,81 +0,0 @@
-[[_ugfun_core-concepts_other-deployment-options]]
-= Other Deployment Options
-: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 is a mature platform suitable for production deployment, with its "sweet spot" being line-of-business enterprise applications.  So if you're looking to develop that sort of application, we certainly hope you'll seriously evaluate it.
-
-But there are other ways that you can make Apache Isis work for you; in this chapter we explore a few of them.
-
-
-
-== Deploy to production
-
-Let's start though with the default use case for Apache Isis: building line-of-business enterprise applications, on top of its Wicket viewer.
-
-Apache Wicket, and therefore Apache Isis in this configuration, is a stateful architecture.  As a platform it is certainly capable of supporting user bases of several thousand (with perhaps one or two hundred concurrent); however it isn't an architecture that you should try to scale up to tens of thousands of concurrent users.
-
-The UI UI generated by the Wicket viewer is well suited to many line-of-business apps, but it's also worth knowing that (with a little knowledge of the Wicket APIs) it relatively straightforward to extend.  As described in xref:../ugfun/ugfun.adoc#_ugfun_core-concepts_add-ons[Isis addons] chapter, the viewer already has integrations with https://github.com/isisaddons/isis-wicket-gmap3[google maps], https://github.com/isisaddons/isis-wicket-fullcalendar2[a full calendar] and an https://github.com/isisaddons/isis-wicket-excel[export to Excel] component.  We are also aware of integrations with SVG images (for floor maps of shopping center) and of custom widgets displaying a catalogue (text and images) of medical diseases.
-
-Deploying on Apache Isis means that the framework also manages object persistence.  For many line-of-business applications this will mean using a relational database.  It is also possible (courtesy of its integratinon with link:http://www.datanucleus.org[DataNucleus]) to deploy an Isis app to a NoSQL store such as Neo4J or MongoDB; and it is also possible to deploy to cloud platforms such as link:https://cloud.google.com/appengine/docs[Google App Engine (GAE)].
-
-
-
-== Use for prototyping
-
-Even if you don't intend to deploy your application on top of Apache Isis, there can be a lot of value in using Apache Isis for prototyping.  Because all you need do to get an app running is write domain objects, you can very quickly explore a domain object model and validate ideas with a domain expert.
-
-By focusing just on the domain, you'll also find that you start to develop a ubiquitous language - a set of terms and concepts that the entire team (business and technologists alike) have a shared understanding.
-
-Once you've sketched out your domain model, you can then "start-over" using your preferred platform.
-
-
-
-
-
-== Deploy on your own platform
-
-The programming model defined by Apache Isis deliberately minimizes the dependencies on the rest of the framework. In fact, the only hard dependency that the domain model classes have on Apache Isis is through the `org.apache.isis.applib` classes, mostly to pick up annotations such as `@Disabled`.
-So, if you have used Apache Isis for prototyping (discussed above), then note that it's quite feasible to take your domain model a the basis of your actual development effort; Apache Isis' annotations and programming conventions will help ensure that any subtle semantics you might have captured in your prototyping are not lost.
-
-If you go this route, your deployment platform will of course need to provide similar capabilities to Apache Isis.  In particular, you'll need to figure out a way to inject domain services into domain entities (eg using a JPA listener), and you'll also need to reimplement any domain services you have used that Apache Isis provides "out-of-the-box" (eg xref:../rgsvc/rgsvc.adoc#_rgsvc_api_QueryResultsCache[`QueryResultsCache`] domain service).
-
-
-
-
-
-== Deploy the REST API
-
-REST (Representation State Transfer) is an architectural style for building highly scalable distributed systems, using the same principles as the World Wide Web. Many commercial web APIs (twitter, facebook, Amazon) are implemented as either pure REST APIs or some approximation therein.
-
-The http://restfulobjects.org[Restful Objects specification] defines a means by a domain object model can be exposed as RESTful resources using JSON representations over HTTP. Apache Isis' xref:../ugvro/ugvro.adoc#[RestfulObjects viewer] is an implementation of that spec, making any Apache Isis domain object automatically available via REST.
-
-There are a number of use cases for deploying Isis as a REST API, including:
-
-* to allow a custom UI to be built against the RESTful API +
-+
-For example, using Angular or some other RIA technology such as Flex, JavaFX, Silverlight
-
-* to enable integration between systems +
-+
-REST is designed to be machine-readable, and so is an excellent choice for synchronous data interchange scenarios.
-
-* as a ready-made API for migrating data from one legacy system to its replacement.
-
-
-As for the auto-generated webapps, the framework manages object persistence. It is perfectly possible to deploy the REST API alongside an auto-generated webapp; both work from the same domain object model.
-
-
-
-
-
-== Implement your own viewer
-
-Isis' architecture was always designed to support multiple viewers; and indeed Apache Isis out-of-the-box supports two: the Wicket viewer, and the Restful Objects viewer (or three, if one includes the Wrapper Factory).
-
-While we mustn't understate the effort involved here, it is feasible to implement your own viewers too.  Indeed, one of Apache Isis' committers does indeed have a (closed source) viewer, based on http://www.wavemaker.com/[Wavemaker].
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology.adoc
deleted file mode 100644
index 580f084..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology.adoc
+++ /dev/null
@@ -1,45 +0,0 @@
-[[_ugfun_domain-class-ontology]]
-= Domain Class Ontology
-: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 supports recognises four main types of domain classes:
-
-* xref:../ugfun/ugfun.adoc#_ugfun_domain-class-ontology_domain-entities[domain entities] - domain objects persisted to the database using JDO/DataNucleus; for example `Customer`
-
-* xref:../ugfun/ugfun.adoc#_ugfun_domain-class-ontology_domain-services[domain services] - generally singletons, automatically injected, and providing various functionality; for example `CustomerRepository`
-
-* xref:../ugfun/ugfun.adoc#_ugfun_domain-class-ontology_view-models[view models] - domain objects that are a projection of some state held by the database, in support a particular use case; for example `CustomerDashboard` (to pull together commonly accessed information about a customer).
-
-* xref:../ugfun/ugfun.adoc#_ugfun_domain-class-ontology_mixins[mixins] - allow functionality to be "contributed" in the UI by one module to another object, similar to traits or extension methods provided in some programming languages.
-This is an important capability to help keep large applications decoupled.
-
-Domain classes are generally recognized using annotations.
-Apache Isis defines its own set of annotations, while entities are annotated using JDO/DataNucleus (though XML can also be used if required).
-JAXB can also be used for view models.
-Apache Isis recognizes some of the JDO and JAXB annotations and infers domain semantics from these annotations.
-
-You can generally recognize an Apache Isis domain class because it will be probably be annotated using `@DomainObject` and `@DomainService`.
-The framework also defines supplementary annotations, `@DomainObjectLayout` and `@DomainServiceLayout`.
-These provide hints relating to the layout of the domain object in the user interface.
-(Alternatively, these UI hints can be defined in a supplementary xref:../ugvw/ugvw.adoc#_ugvw_layout[`.layout.xml`] file.
-
-We use Maven modules as a way to group related domain objects together; we can then reason about all the classes in that module as a single unit.
-By convention there will be a single top-level package corresponding to the module.
-
-For example, the (non-ASF) link:https://github.com/incodehq/incode-module-document[Document module] (part of the link:http://catalog.incode.org[Incode Catalog]) has a top-level package of `org.incode.module.document`.
-Within the module there may be various subpackages, but its the module defines the namespace.
-
-In the same way that the Java module act as a namespace for domain objects, it's good practice to map domain entities to their own (database) schemas.
-
-
-
-include::_ugfun_domain-class-ontology_domain-entities.adoc[leveloffset=+1]
-include::_ugfun_domain-class-ontology_domain-services.adoc[leveloffset=+1]
-include::_ugfun_domain-class-ontology_view-models.adoc[leveloffset=+1]
-include::_ugfun_domain-class-ontology_mixins.adoc[leveloffset=+1]
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_domain-entities.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_domain-entities.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_domain-entities.adoc
deleted file mode 100644
index ce399e3..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_domain-entities.adoc
+++ /dev/null
@@ -1,86 +0,0 @@
-[[_ugfun_domain-class-ontology_domain-entities]]
-= Domain Entities
-: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/
-
-
-
-Entities are persistent domain objects, with their persistence handled by JDO/DataNucleus.
-As such, they are mapped to a persistent object store, typically an RDBMS, with DataNucleus taking care of both lazy loading and also the persisting of modified ("dirty") objects.
-
-Domain entities are generally decorated with both DataNucleus and Apache Isis annotations.
-The following is typical:
-
-[source,java]
-----
-@javax.jdo.annotations.PersistenceCapable(                                      // <1>
-        identityType=IdentityType.DATASTORE,                                    // <2>
-        schema = "simple",                                                      // <3>
-        table = "SimpleObject"
-)
-@javax.jdo.annotations.DatastoreIdentity(                                       // <4>
-        strategy=javax.jdo.annotations.IdGeneratorStrategy.IDENTITY,
-        column="id"
-)
-@javax.jdo.annotations.Version(                                                 // <5>
-        strategy= VersionStrategy.DATE_TIME,
-        column="version"
-)
-@javax.jdo.annotations.Queries({
-        @javax.jdo.annotations.Query(                                           // <6>
-                name = "findByName",
-                value = "SELECT "
-                        + "FROM domainapp.modules.simple.dom.impl.SimpleObject "
-                        + "WHERE name.indexOf(:name) >= 0 ")
-})
-@javax.jdo.annotations.Unique(name="SimpleObject_name_UNQ", members = {"name"}) // <7>
-@DomainObject(                                                                  // <8>
-        objectType = "simple.SimpleObject"
-)
-public class SimpleObject
-             implements Comparable<SimpleObject> {                              // <9>
-
-    public SimpleObject(final String name) {                                    // <10>
-        setName(name);
-    }
-
-    ...
-
-    @Override
-    public String toString() {
-        return ObjectContracts.toString(this, "name");                          // <11>
-    }
-    @Override
-    public int compareTo(final SimpleObject other) {
-        return ObjectContracts.compare(this, other, "name");                    // <9>
-    }
-}
-----
-<1> The `@PersistenceCapable` annotation indicates that this is an entity to DataNucleus.
-The DataNucleus enhancer acts on the bytecode of compiled entities, injecting lazy loading and dirty object tracking functionality.
-Enhanced entities end up also implementing the `javax.jdo.spi.PersistenceCapable` interface.
-<2> Indicates how identifiers for the entity are handled.
-Using `DATASTORE` means that a DataNucleus is responsible for assigning the value (rather than the application).
-<3> Specifies the RDBMS database schema and table name for this entity will reside.
-The schema should correspond with the module in which the entity resides.
-The table will default to the entity name if omitted.
-<4> For entities that are using `DATASTORE` identity, indicates how the id will be assigned.
-A common strategy is to allow the database to assign the id, for example using an identity column or a sequence.
-<5> The `@Version` annotation is useful for optimistic locking; the strategy indicates what to store in the `version` column.
-<6> The `@Query` annotation (usually several of them, nested within a `@Queries` annotation) defines queries using JDOQL.
-DataNucleus provides several APIs for defining queries, including entirely programmatic and type-safe APIs; but JDOQL is very similar to SQL and so easily learnt.
-<7> DataNucleus will automatically add a unique index to the primary surrogate id (discussed above), but additional alternative keys can be defined using the `@Unique` annotation.
-In the example above, the "name" property is assumed to be unique.
-<8> The `@DomainObject` annotation identifies the domain object to Apache Isis (not DataNucleus).
-It isn't necessary to include this annotation -- at least, not for entities -- but it is nevertheless recommended.
-In particular, its strongly recommended that the `objectType` (which acts like an alias to the concrete domain class) is specified; note that it corresponds to the schema/table for DataNucleus' `@PersistenceCapable` annotation.
-<9> Although not required, we strongly recommend that all entities are naturally `Comparable`.
-This then allows parent/child relationships to be defined using ``SortedSet``s; RDBMS after all are set-oriented.
-The `ObjectContracts` utility class provided by Apache Isis makes it easy to implement the `compareTo()` method, but you can also just use an IDE to generate an implementation or roll your own.
-<10> Chances are that some of the properties of the entity will be mandatory, for example any properties that represent an alternate unique key to the entity.
-In regular Java programming we would represent this using a constructor that defines these mandatory properties, and in Apache Isis/DataNucleus we can likewise define such a constructor.
-When DataNucleus rehydrates domain entities from the database at runtime, it actually requires a no-arg constructor (it then sets all state reflectively).
-However, there is no need to provide such a no-arg constructor; it is added by the enhancer process.
-<11> The `ObjectContracts` utility class also provides assistance for `toString()`, useful when debugging in an IDE.
-

[09/58] [abbrv] isis git commit: ISIS-1521: fixes xref links between guides

[da...@apache.org]

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_lifecycle.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_lifecycle.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_lifecycle.adoc
index 309c136..87c1ecc 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_lifecycle.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_lifecycle.adoc
@@ -14,9 +14,9 @@ The lifecycle callback methods notify a domain entity about its interaction with
 Note that these callbacks are fired by Apache Isis rather than JDO.  In the future we may deprecate them because there are better mechanisms available using listeners/subscribers:
 
 * in Isis 1.9.0 and earlier, you may therefore want to consider using the JDO API directly to set up a lifecycle
-listener; see xref:rgcms.adoc#_rgcms_methods_lifecycle_jdo-api[here] for further discussion.
+listener; see xref:../rgcms/rgcms.adoc#_rgcms_methods_lifecycle_jdo-api[here] for further discussion.
 
-* alternatively, you can use a subscriber for the xref:rgcms.adoc#_rgcms_classes_lifecycleevent[lifecycle event]s fired in Isis.
+* alternatively, you can use a subscriber for the xref:../rgcms/rgcms.adoc#_rgcms_classes_lifecycleevent[lifecycle event]s fired in Isis.
 ====
 
 The lifecycle callback methods supported by Isis are:
@@ -28,28 +28,28 @@ The lifecycle callback methods supported by Isis are:
 |Method
 |Description
 
-|xref:rgcms.adoc#_rgcms_methods_lifecycle_created[`created()`]
-|called when an object has just been created using xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`newTransientInstance()`]
+|xref:../rgcms/rgcms.adoc#_rgcms_methods_lifecycle_created[`created()`]
+|called when an object has just been created using xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`newTransientInstance()`]
 
-|xref:rgcms.adoc#_rgcms_methods_lifecycle_loaded[`loaded()`]
+|xref:../rgcms/rgcms.adoc#_rgcms_methods_lifecycle_loaded[`loaded()`]
 |called when a (persistent) object has just been loaded from the object store.
 
-|xref:rgcms.adoc#_rgcms_methods_lifecycle_persisted[`persisted()`]
+|xref:../rgcms/rgcms.adoc#_rgcms_methods_lifecycle_persisted[`persisted()`]
 |called when object has just been persisted from the object store.
 
-|xref:rgcms.adoc#_rgcms_methods_lifecycle_persisting[`persisting()`]
+|xref:../rgcms/rgcms.adoc#_rgcms_methods_lifecycle_persisting[`persisting()`]
 |called when a (not-yet-persistent) object is just about to be persisted from the object store
 
-|xref:rgcms.adoc#_rgcms_methods_lifecycle_removed[`removed()`]
+|xref:../rgcms/rgcms.adoc#_rgcms_methods_lifecycle_removed[`removed()`]
 |called when a (persistent) object has just been deleted from the object store
 
-|xref:rgcms.adoc#_rgcms_methods_lifecycle_removing[`removing()`]
+|xref:../rgcms/rgcms.adoc#_rgcms_methods_lifecycle_removing[`removing()`]
 |called when a (persistent) object is just about to be deleted from the object store
 
-|xref:rgcms.adoc#_rgcms_methods_lifecycle_updated[`updated()`]
+|xref:../rgcms/rgcms.adoc#_rgcms_methods_lifecycle_updated[`updated()`]
 |called when a (persistent) object has just been updated in the object store
 
-|xref:rgcms.adoc#_rgcms_methods_lifecycle_updating[`updating()`]
+|xref:../rgcms/rgcms.adoc#_rgcms_methods_lifecycle_updating[`updating()`]
 |called when a (persistent) object is just about to be updated in the object store
 
 |===
@@ -66,10 +66,10 @@ Some lifecycle methods have been deprecated:
 |Notes
 
 |`deleted()`
-|Replaced by xref:rgcms.adoc#_rgcms_methods_lifecycle_removed[`removed()`]
+|Replaced by xref:../rgcms/rgcms.adoc#_rgcms_methods_lifecycle_removed[`removed()`]
 
 |`deleting()`
-|Replaced by xref:rgcms.adoc#_rgcms_methods_lifecycle_removing[`removing()`]
+|Replaced by xref:../rgcms/rgcms.adoc#_rgcms_methods_lifecycle_removing[`removing()`]
 
 |`loading()`
 |callback for when the (persistent) object is just about to be loaded from the object store. +
@@ -80,10 +80,10 @@ This method is never called.
 ====
 
 |`saved()`
-|Replaced by xref:rgcms.adoc#_rgcms_methods_lifecycle_persisted[`persisted()`]
+|Replaced by xref:../rgcms/rgcms.adoc#_rgcms_methods_lifecycle_persisted[`persisted()`]
 
 |`saving()`
-|Replaced by xref:rgcms.adoc#_rgcms_methods_lifecycle_persisting[`persisting()`]
+|Replaced by xref:../rgcms/rgcms.adoc#_rgcms_methods_lifecycle_persisting[`persisting()`]
 
 |===
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_lifecycle_created.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_lifecycle_created.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_lifecycle_created.adoc
index 604689b..7880866 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_lifecycle_created.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_lifecycle_created.adoc
@@ -5,12 +5,12 @@
 :_imagesdir: images/
 
 
-The `created()` lifecycle callback method is called when an object has just been created using xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`newTransientInstance()`]
+The `created()` lifecycle callback method is called when an object has just been created using xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`newTransientInstance()`]
 
 
 [TIP]
 ====
-Alternatively, consider using a xref:rgsvc.adoc#_rgsvc_api_EventBusService[event bus] xref:rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscriber] on the xref:rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectCreatedEvent[`ObjectCreatedEvent`].
+Alternatively, consider using a xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[event bus] xref:../rgcms/rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscriber] on the xref:../rgcms/rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectCreatedEvent[`ObjectCreatedEvent`].
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_lifecycle_jdo-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_lifecycle_jdo-api.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_lifecycle_jdo-api.adoc
index bf159ff..3192f2d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_lifecycle_jdo-api.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_lifecycle_jdo-api.adoc
@@ -13,7 +13,7 @@ As an alternative to relying on Apache Isis to call lifecycle callback methods,
 We may decide to deprecate the Apache Isis callbacks in the future because they merely duplicate this functionality already available in JDO.
 ====
 
-You can gain access to the relevant JDO API using the xref:rgsvc.adoc#_rgsvc_api_IsisJdoSupport[`IsisJdoSupport`] domain service.
+You can gain access to the relevant JDO API using the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_IsisJdoSupport[`IsisJdoSupport`] domain service.
 
 For example:
 
@@ -46,7 +46,7 @@ public class ObjectChangedListenerService
 ----
 <1> must be `@RequestScoped` because we register on the `PersistenceManager`, which is different for each request.
 <2> implement whichever callback lifecycle listeners are of interest
-<3> use the injected xref:rgsvc.adoc#_rgsvc_api_IsisJdoSupport[`IsisJdoSupport`] service to obtain the `PersistenceManager`.
+<3> use the injected xref:../rgsvc/rgsvc.adoc#_rgsvc_api_IsisJdoSupport[`IsisJdoSupport`] service to obtain the `PersistenceManager`.
 
 Note that it isn't possible to register on the `PersistenceManagerFactory` because listeners cannot be attached once a persistence session has been created (which it will have been when the service's `@PostConstruct` method is called).
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_lifecycle_loaded.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_lifecycle_loaded.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_lifecycle_loaded.adoc
index a9c5ebd..382c30d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_lifecycle_loaded.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_lifecycle_loaded.adoc
@@ -11,5 +11,5 @@ The `loaded()` lifecycle callback method is called when a (persistent) object ha
 
 [TIP]
 ====
-Alternatively, consider using a xref:rgsvc.adoc#_rgsvc_api_EventBusService[event bus] xref:rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscriber] on the xref:rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectLoadedEvent[`ObjectLoadedEvent`].
+Alternatively, consider using a xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[event bus] xref:../rgcms/rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscriber] on the xref:../rgcms/rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectLoadedEvent[`ObjectLoadedEvent`].
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_lifecycle_persisted.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_lifecycle_persisted.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_lifecycle_persisted.adoc
index d885d8d..10c5155 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_lifecycle_persisted.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_lifecycle_persisted.adoc
@@ -8,9 +8,9 @@
 
 The `persisted()` lifecycle callback method is called when object has just been persisted from the object store.
 
-See also xref:rgcms.adoc#_rgcms_methods_lifecycle_persisting[`persisting()`].
+See also xref:../rgcms/rgcms.adoc#_rgcms_methods_lifecycle_persisting[`persisting()`].
 
 [TIP]
 ====
-Alternatively, consider using a xref:rgsvc.adoc#_rgsvc_api_EventBusService[event bus] xref:rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscriber] on the xref:rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectPersistedEvent[`ObjectPersistedEvent`].
+Alternatively, consider using a xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[event bus] xref:../rgcms/rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscriber] on the xref:../rgcms/rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectPersistedEvent[`ObjectPersistedEvent`].
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_lifecycle_persisting.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_lifecycle_persisting.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_lifecycle_persisting.adoc
index 0a91570..c6929e2 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_lifecycle_persisting.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_lifecycle_persisting.adoc
@@ -8,9 +8,9 @@
 
 The `persisting()` lifecycle callback method is called when a (not-yet-persistent) object is just about to be persisted from the object store
 
-See also xref:rgcms.adoc#_rgcms_methods_lifecycle_persisted[`persisted()`].
+See also xref:../rgcms/rgcms.adoc#_rgcms_methods_lifecycle_persisted[`persisted()`].
 
 [TIP]
 ====
-Alternatively, consider using a xref:rgsvc.adoc#_rgsvc_api_EventBusService[event bus] xref:rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscriber] on the xref:rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectPersistingEvent[`ObjectPersistingEvent`].
+Alternatively, consider using a xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[event bus] xref:../rgcms/rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscriber] on the xref:../rgcms/rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectPersistingEvent[`ObjectPersistingEvent`].
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_lifecycle_removed.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_lifecycle_removed.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_lifecycle_removed.adoc
index ac41176..8b814ff 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_lifecycle_removed.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_lifecycle_removed.adoc
@@ -8,9 +8,9 @@
 
 The `removed()` lifecycle callback method is called when a (persistent) object has just been deleted from the object store
 
-See also xref:rgcms.adoc#_rgcms_methods_lifecycle_removing[`removing()`].
+See also xref:../rgcms/rgcms.adoc#_rgcms_methods_lifecycle_removing[`removing()`].
 
 [TIP]
 ====
-Alternatively, consider using a xref:rgsvc.adoc#_rgsvc_api_EventBusService[event bus] xref:rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscriber] on the xref:rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectRemovedEvent[`ObjectRemovedEvent`].
+Alternatively, consider using a xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[event bus] xref:../rgcms/rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscriber] on the xref:../rgcms/rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectRemovedEvent[`ObjectRemovedEvent`].
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_lifecycle_removing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_lifecycle_removing.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_lifecycle_removing.adoc
index a0da399..ca51dde 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_lifecycle_removing.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_lifecycle_removing.adoc
@@ -8,9 +8,9 @@
 
 The `removing()` lifecycle callback method is called when a (persistent) object is just about to be deleted from the object store
 
-See also xref:rgcms.adoc#_rgcms_methods_lifecycle_removed[`removed()`].
+See also xref:../rgcms/rgcms.adoc#_rgcms_methods_lifecycle_removed[`removed()`].
 
 [TIP]
 ====
-Alternatively, consider using a xref:rgsvc.adoc#_rgsvc_api_EventBusService[event bus] xref:rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscriber] on the xref:rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectRemovingEvent[`ObjectRemovingEvent`].
+Alternatively, consider using a xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[event bus] xref:../rgcms/rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscriber] on the xref:../rgcms/rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectRemovingEvent[`ObjectRemovingEvent`].
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_lifecycle_updated.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_lifecycle_updated.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_lifecycle_updated.adoc
index 244f4be..7f4923e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_lifecycle_updated.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_lifecycle_updated.adoc
@@ -10,9 +10,9 @@
 
 The `updated()` lifecycle callback method is called when a (persistent) object has just been updated in the object store
 
-See also xref:rgcms.adoc#_rgcms_methods_lifecycle_updating[`updating()`].
+See also xref:../rgcms/rgcms.adoc#_rgcms_methods_lifecycle_updating[`updating()`].
 
 [TIP]
 ====
-Alternatively, consider using a xref:rgsvc.adoc#_rgsvc_api_EventBusService[event bus] xref:rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscriber] on the xref:rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectUpdatedEvent[`ObjectUpdatedEvent`].
+Alternatively, consider using a xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[event bus] xref:../rgcms/rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscriber] on the xref:../rgcms/rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectUpdatedEvent[`ObjectUpdatedEvent`].
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_lifecycle_updating.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_lifecycle_updating.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_lifecycle_updating.adoc
index acd535f..d3ffb3a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_lifecycle_updating.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_lifecycle_updating.adoc
@@ -7,9 +7,9 @@
 
 The `updating()` lifecycle callback method is called when a (persistent) object is just about to be updated in the object store
 
-See also xref:rgcms.adoc#_rgcms_methods_lifecycle_updated[`updated()`].
+See also xref:../rgcms/rgcms.adoc#_rgcms_methods_lifecycle_updated[`updated()`].
 
 [TIP]
 ====
-Alternatively, consider using a xref:rgsvc.adoc#_rgsvc_api_EventBusService[event bus] xref:rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscriber] on the xref:rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectUpdatingEvent[`ObjectUpdatingEvent`].
+Alternatively, consider using a xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[event bus] xref:../rgcms/rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscriber] on the xref:../rgcms/rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectUpdatingEvent[`ObjectUpdatingEvent`].
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes.adoc
index 5eacd97..25cde24 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes.adoc
@@ -34,7 +34,7 @@ The table below lists the method prefixes that are recognized as part of Apache
 Param
 |Description
 
-|xref:rgcms.adoc#_rgcms_methods_prefixes_addTo[`addTo...()`]
+|xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_addTo[`addTo...()`]
 |
 |
 |Y
@@ -47,10 +47,10 @@ Param
 Directly mutable collections are not currently supported by the xref:ugvw.adoc#[Wicket viewer].
 ====
 
-See also xref:rgcms.adoc#_rgcms_methods_prefixes_removeFrom[`removeFrom...()`]`
+See also xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_removeFrom[`removeFrom...()`]`
 
 
-|xref:rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`]
+|xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`]
 |
 |Y
 |
@@ -58,12 +58,12 @@ See also xref:rgcms.adoc#_rgcms_methods_prefixes_removeFrom[`removeFrom...()`]`
 |Y
 |Return a list of matching elements for a property or an action parameter. +
 
-Alternatively, can specify for a class using xref:rgant.adoc#_rgant-DomainObject_autoCompleteRepository[`@DomainObject` +
+Alternatively, can specify for a class using xref:../rgant/rgant.adoc#_rgant-DomainObject_autoCompleteRepository[`@DomainObject` +
 `#autoCompleteRepository`] +
 
-See also xref:rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`]
+See also xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`]
 
-|xref:rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`]
+|xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`]
 |
 |Y
 |
@@ -71,9 +71,9 @@ See also xref:rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`]
 |Y
 |Provide list of choices for a property or action parameter. +
 
-See also xref:rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`].
+See also xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`].
 
-|xref:rgcms.adoc#_rgcms_methods_prefixes_clear[`clear...()`]
+|xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_clear[`clear...()`]
 |
 |Y
 |
@@ -83,10 +83,10 @@ See also xref:rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()
 
 Allows business logic to be placed apart from the setter. +
 
-See also xref:rgcms.adoc#_rgcms_methods_prefixes_modify[`modify...()`]
+See also xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_modify[`modify...()`]
 
 
-|xref:rgcms.adoc#_rgcms_methods_prefixes_default[`default...()`]
+|xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_default[`default...()`]
 |
 |Y
 |
@@ -94,7 +94,7 @@ See also xref:rgcms.adoc#_rgcms_methods_prefixes_modify[`modify...()`]
 |Y
 |Default value for a property or an action parameter.
 
-|xref:rgcms.adoc#_rgcms_methods_prefixes_disable[`disable...()`]
+|xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_disable[`disable...()`]
 |Y
 |Y
 |Y
@@ -102,7 +102,7 @@ See also xref:rgcms.adoc#_rgcms_methods_prefixes_modify[`modify...()`]
 |
 |Disables (makes read-only) a property, a collection or an action.
 
-|xref:rgcms.adoc#_rgcms_methods_prefixes_get[`get...()`]
+|xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_get[`get...()`]
 |
 |Y
 |Y
@@ -110,9 +110,9 @@ See also xref:rgcms.adoc#_rgcms_methods_prefixes_modify[`modify...()`]
 |
 |Access the value of a property or collection. +
 
-See also xref:rgcms.adoc#_rgcms_methods_prefixes_set[`set...()`].
+See also xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_set[`set...()`].
 
-|xref:rgcms.adoc#_rgcms_methods_prefixes_hide[`hide...()`]
+|xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_hide[`hide...()`]
 |
 |Y
 |Y
@@ -120,7 +120,7 @@ See also xref:rgcms.adoc#_rgcms_methods_prefixes_set[`set...()`].
 |
 |Hides a property, a collection or an action.
 
-|xref:rgcms.adoc#_rgcms_methods_prefixes_modify[`modify...()`]
+|xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_modify[`modify...()`]
 |
 |Y
 |
@@ -130,9 +130,9 @@ See also xref:rgcms.adoc#_rgcms_methods_prefixes_set[`set...()`].
 
 Allows business logic to be placed apart from the setter. +
 
-See also xref:rgcms.adoc#_rgcms_methods_prefixes_clear[`clear...()`]`.
+See also xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_clear[`clear...()`]`.
 
-|xref:rgcms.adoc#_rgcms_methods_prefixes_removeFrom[`removeFrom...()`]
+|xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_removeFrom[`removeFrom...()`]
 |
 |
 |Y
@@ -145,10 +145,10 @@ See also xref:rgcms.adoc#_rgcms_methods_prefixes_clear[`clear...()`]`.
 Directly mutable collections are not currently supported by the xref:ugvw.adoc#[Wicket viewer].
 ====
 
-See also xref:rgcms.adoc#_rgcms_methods_prefixes_addTo[`addTo...()`]`
+See also xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_addTo[`addTo...()`]`
 
 
-|xref:rgcms.adoc#_rgcms_methods_prefixes_set[`set...()`]
+|xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_set[`set...()`]
 |
 |Y
 |Y
@@ -156,7 +156,7 @@ See also xref:rgcms.adoc#_rgcms_methods_prefixes_addTo[`addTo...()`]`
 |
 |Sets the value of a property or a collection.
 
-|xref:rgcms.adoc#_rgcms_methods_prefixes_validate[`validate...()`]
+|xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_validate[`validate...()`]
 |Y
 |
 |
@@ -164,9 +164,9 @@ See also xref:rgcms.adoc#_rgcms_methods_prefixes_addTo[`addTo...()`]`
 |Y
 |Check that a proposed value of a property or a set of action parameters or a single action parameter is valid. +
 
-See also xref:rgcms.adoc#_rgcms_methods_prefixes_validateAddTo[`validateAddTo...()`] and xref:rgcms.adoc#_rgcms_methods_prefixes_validateRemoveFrom[`validateRemoveFrom...()`] to validate modifications to collections.
+See also xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_validateAddTo[`validateAddTo...()`] and xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_validateRemoveFrom[`validateRemoveFrom...()`] to validate modifications to collections.
 
-|xref:rgcms.adoc#_rgcms_methods_prefixes_validateAddTo[`validate +
+|xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_validateAddTo[`validate +
 AddTo...()`]
 |
 |Y
@@ -180,9 +180,9 @@ AddTo...()`]
 Directly mutable collections are not currently supported by the xref:ugvw.adoc#[Wicket viewer].
 ====
 
-See also xref:rgcms.adoc#_rgcms_methods_prefixes_validateRemoveFrom[`validateRemoveFrom...()`], and xref:rgcms.adoc#_rgcms_methods_prefixes_validate[`validate...()`] for properties and actions.
+See also xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_validateRemoveFrom[`validateRemoveFrom...()`], and xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_validate[`validate...()`] for properties and actions.
 
-|xref:rgcms.adoc#_rgcms_methods_prefixes_validateRemoveFrom[`validate +
+|xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_validateRemoveFrom[`validate +
 RemoveFrom...()`]
 |
 |Y
@@ -196,7 +196,7 @@ RemoveFrom...()`]
 Directly mutable collections are not currently supported by the xref:ugvw.adoc#[Wicket viewer].
 ====
 
-See also xref:rgcms.adoc#_rgcms_methods_prefixes_validateAddTo[`validateAddTo...()`], and xref:rgcms.adoc#_rgcms_methods_prefixes_validate[`validate...()`] for properties and actions.
+See also xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_validateAddTo[`validateAddTo...()`], and xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_validate[`validate...()`] for properties and actions.
 
 |===
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_addTo.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_addTo.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_addTo.adoc
index 14b570d..5ab34de 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_addTo.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_addTo.adoc
@@ -34,4 +34,4 @@ public class LibraryMember {
 <2> perform some additional business logic
 
 
-See also xref:rgcms.adoc#_rgcms_methods_prefixes_removeFrom[`removeFrom...()`]`
+See also xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_removeFrom[`removeFrom...()`]`

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_autoComplete.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_autoComplete.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_autoComplete.adoc
index ca0f1cb..4536425 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_autoComplete.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_autoComplete.adoc
@@ -10,7 +10,7 @@ The `autoComplete...()` supporting method is called for action parameters and fo
 
 [TIP]
 ====
-If the number of candidate objects is comparatively small, then use xref:rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`] supporting method instead.
+If the number of candidate objects is comparatively small, then use xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`] supporting method instead.
 ====
 
 The signature of the supporting method depends on whether it is for a parameter or a property.
@@ -58,7 +58,7 @@ public class ShoppingCartItem {
 }
 ----
 <1> `product` is the 0th argument of the action.
-<2> the xref:rgant.adoc#_rgant-MinLength[`@MinLength`] annotation specifies the minimum number of characters that must be entered before a search is performed for matching objects
+<2> the xref:../rgant/rgant.adoc#_rgant-MinLength[`@MinLength`] annotation specifies the minimum number of characters that must be entered before a search is performed for matching objects
 
 
 
@@ -91,6 +91,6 @@ public class ShoppingCartItem {
     ...
 }
 ----
-<1> the xref:rgant.adoc#_rgant-MinLength[`@MinLength`] annotation specifies the minimum number of characters that must be entered before a search is performed for matching objects
+<1> the xref:../rgant/rgant.adoc#_rgant-MinLength[`@MinLength`] annotation specifies the minimum number of characters that must be entered before a search is performed for matching objects
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_choices.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_choices.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_choices.adoc
index dd4f094..8f7d980 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_choices.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_choices.adoc
@@ -6,7 +6,7 @@
 
 
 
-The `choices...()` supporting method is called for both action parameters and for properties, to find objects from a drop-down list box.  Unlike xref:rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`], the use case is when the number of objects is comparatively small and can be selected from a drop-down without any additional filtering.
+The `choices...()` supporting method is called for both action parameters and for properties, to find objects from a drop-down list box.  Unlike xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`], the use case is when the number of objects is comparatively small and can be selected from a drop-down without any additional filtering.
 
 The signature of the supporting method depends on whether it is for an action parameter or a property.
 
@@ -60,7 +60,7 @@ image::{_imagesdir}reference-methods/prefixes/choices/dependent.png[width="800px
 
 
 
-This functionality is actually implemented as a xref:ugfun.adoc#_ugfun_how-tos_contributed-members[contributed action], so the code for this is:
+This functionality is actually implemented as a xref:../ugfun/ugfun.adoc#_ugfun_how-tos_contributed-members[contributed action], so the code for this is:
 
 [source,java]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_clear.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_clear.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_clear.adoc
index 312a946..a70856e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_clear.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_clear.adoc
@@ -29,4 +29,4 @@ public class LibraryMember {
 <2> perform some additional business logic
 
 
-See also xref:rgcms.adoc#_rgcms_methods_prefixes_modify[`modify...()`]`
+See also xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_modify[`modify...()`]`

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_default.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_default.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_default.adoc
index 24ecfff..a3f0e81 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_default.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_default.adoc
@@ -8,7 +8,7 @@
 
 The `default...()` supporting method is called for action parameters to return the initial argument value.  This may be some sensible default (eg today's date, or 0 or 1), or -- for an action that is modifying the state of an object -- might default to the current value of a corresponding property.
 
-The method is _also_ called for properties in the case when an object is newly instantiated using xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer#newTransientInstance(...)`].  This is a much less common use case.  If a default is not specified then properties are initialized to a default based on their type (eg 0 or `false`).
+The method is _also_ called for properties in the case when an object is newly instantiated using xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer#newTransientInstance(...)`].  This is a much less common use case.  If a default is not specified then properties are initialized to a default based on their type (eg 0 or `false`).
 
 The signature of the supporting method depends on whether it is for an action parameter or a property.
 
@@ -58,7 +58,7 @@ public class ShoppingCartItem {
 
 
 
-Defaults are also supported (of course) for xref:ugfun.adoc#_ugfun_how-tos_contributed-members[contributed actions].  For example, here is a contributed action for updating category/subcategory of the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp]:
+Defaults are also supported (of course) for xref:../ugfun/ugfun.adoc#_ugfun_how-tos_contributed-members[contributed actions].  For example, here is a contributed action for updating category/subcategory of the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp]:
 
 [source,java]
 ----
@@ -123,7 +123,7 @@ public class ShoppingCartItem {
 
 There are, in fact, two other ways to set properties of a newly instantiated object to default values.
 
-The first is to use the xref:rgcms.adoc#_rgcms_methods_lifecycle_created[`created()`] callback, called by the framework when xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer#newTransientInstance(...)`] is called.  This method is called after any dependencies have been injected into the service.
+The first is to use the xref:../rgcms/rgcms.adoc#_rgcms_methods_lifecycle_created[`created()`] callback, called by the framework when xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer#newTransientInstance(...)`] is called.  This method is called after any dependencies have been injected into the service.
 
 The second is more straightforward: simply initialize properties in the constructor.  However, this cannot use any injected services as they will not have been initialized.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_disable.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_disable.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_disable.adoc
index c1869ae..16ca889 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_disable.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_disable.adoc
@@ -89,6 +89,6 @@ public class Customer {
 In the case of actions, the framework will also search for supporting method that has the exact same parameter types as the action itself.
 Enabling `isis.reflector.validator.noParamsOnly` configuration property switches this off, so that the framework will only search for supporting method with no parameters.
 
-Note that enabling this configuration property in effect means that xref:rgcms.adoc#_rgcms_classes_mixins[mixins] must be used instead of xref:ugbtb.adoc#_ugbtb_decoupling_contributions[contributed services] (because contributed actions are the one case where the value of a parameter to a supporting method may be non-null).
+Note that enabling this configuration property in effect means that xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins[mixins] must be used instead of xref:ugbtb.adoc#_ugbtb_decoupling_contributions[contributed services] (because contributed actions are the one case where the value of a parameter to a supporting method may be non-null).
 ====
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_get.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_get.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_get.adoc
index 977a149..0923c86 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_get.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_get.adoc
@@ -15,5 +15,5 @@ All remaining `public` methods (that do not use one of the Apache Isis prefixes)
 Any methods "left over" that _do_ use one of the Apache Isis prefixes, are interpreted to be orphaned.  Apache Isis "fails-fast" and will not boot, instead printing an error message to the log so that the issue can be easily diagnosed.
 
 
-See also xref:rgcms.adoc#_rgcms_methods_prefixes_set[`set...()`].
+See also xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_set[`set...()`].
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_hide.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_hide.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_hide.adoc
index 214e580..7566041 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_hide.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_hide.adoc
@@ -9,7 +9,7 @@
 The `hide...()` supporting method is called for properties, collections and actions.
 It allows the property/collection to be completely hidden from view.
 
-It's comparatively rare for properties or collections to be imperatively hidden from view, but actions are sometimes hidden or shown visible (as opposed to being just xref:rgcms.adoc#_rgcms_methods_prefixes_disable[disabled], ie greyed out).
+It's comparatively rare for properties or collections to be imperatively hidden from view, but actions are sometimes hidden or shown visible (as opposed to being just xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_disable[disabled], ie greyed out).
 
 
 The signature of the supporting method is simply:
@@ -65,6 +65,6 @@ public class Customer {
 In the case of actions, the framework will also search for supporting method that has the exact same parameter types as the action itself.
 Enabling `isis.reflector.validator.noParamsOnly` configuration property switches this off, so that the framework will only search for supporting method with no parameters.
 
-Note that enabling this configuration property in effect means that xref:rgcms.adoc#_rgcms_classes_mixins[mixins] must be used instead of xref:ugbtb.adoc#_ugbtb_decoupling_contributions[contributed services] (because contributed actions are the one case where the value of a parameter to a supporting method may be non-null).
+Note that enabling this configuration property in effect means that xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins[mixins] must be used instead of xref:ugbtb.adoc#_ugbtb_decoupling_contributions[contributed services] (because contributed actions are the one case where the value of a parameter to a supporting method may be non-null).
 ====
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_modify.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_modify.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_modify.adoc
index 53a1c87..bc41a70 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_modify.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_modify.adoc
@@ -32,6 +32,6 @@ public class LibraryMember {
 <3> perform some additional business logic
 
 
-See also xref:rgcms.adoc#_rgcms_methods_prefixes_clear[`clear...()`]`
+See also xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_clear[`clear...()`]`
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_removeFrom.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_removeFrom.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_removeFrom.adoc
index 5a965f2..e7e07fa 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_removeFrom.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_removeFrom.adoc
@@ -34,4 +34,4 @@ public class LibraryMember {
 <2> perform some additional business logic
 
 
-See also xref:rgcms.adoc#_rgcms_methods_prefixes_addTo[`addTo...()`]`
+See also xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_addTo[`addTo...()`]`

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_set.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_set.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_set.adoc
index a143d22..cb2ffbf 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_set.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_set.adoc
@@ -10,4 +10,4 @@
 The `set...()` prefix is simply the normal JavaBean setter prefix that denotes writeable properties or collections.
 
 
-See also xref:rgcms.adoc#_rgcms_methods_prefixes_get[`get...()`].
+See also xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_get[`get...()`].

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_validateAddTo.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_validateAddTo.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_validateAddTo.adoc
index 795d152..afb2550 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_validateAddTo.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_validateAddTo.adoc
@@ -41,5 +41,5 @@ public class LibraryMember {
 ----
 
 
-See also xref:rgcms.adoc#_rgcms_methods_prefixes_addTo[`addTo...()`] and  xref:rgcms.adoc#_rgcms_methods_prefixes_validateRemoveFrom[`validateRemoveFrom...()`]`
+See also xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_addTo[`addTo...()`] and  xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_validateRemoveFrom[`validateRemoveFrom...()`]`
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_validateRemoveFrom.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_validateRemoveFrom.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_validateRemoveFrom.adoc
index d8f5a2e..acbd98e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_validateRemoveFrom.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_validateRemoveFrom.adoc
@@ -41,5 +41,5 @@ public class LibraryMember {
 ----
 
 
-See also xref:rgcms.adoc#_rgcms_methods_prefixes_removeFrom[`removeFrom...()`] and  xref:rgcms.adoc#_rgcms_methods_prefixes_validateAddTo[`validateAddTo...()`]`
+See also xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_removeFrom[`removeFrom...()`] and  xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_validateAddTo[`validateAddTo...()`]`
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved.adoc
index 90cb286..929b5ec 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved.adoc
@@ -15,33 +15,33 @@ The table below lists the reserved methods that are recognized as part of Apache
 |Method
 |Description
 
-|xref:rgcms.adoc#_rgcms_methods_reserved_cssClass[`cssClass()`]
-|Provides a CSS class for this object instance.  In conjunction with xref:rgcfg.adoc#_rgcfg_application-specific_application-css[`application.css`], can therefore provide custom styling of an object instance wherever it is rendered. +
+|xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_cssClass[`cssClass()`]
+|Provides a CSS class for this object instance.  In conjunction with xref:../rgcfg/rgcfg.adoc#_rgcfg_application-specific_application-css[`application.css`], can therefore provide custom styling of an object instance wherever it is rendered. +
 
-See also xref:rgcms.adoc#_rgcms_methods_reserved_title[`title()`] and xref:rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`].
+See also xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_title[`title()`] and xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`].
 
-|xref:rgcms.adoc#_rgcms_methods_reserved_disable[`disable(...)`]
+|xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_disable[`disable(...)`]
 |Disable all or some of an object's properties
 
-|xref:rgcms.adoc#_rgcms_methods_reserved_getId[`getId()`]
+|xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_getId[`getId()`]
 |Provides an optional unique identifier of a service. +
 
 If not provided, the service's fully-qualified class name is used.
 
-|xref:rgcms.adoc#_rgcms_methods_reserved_hide[`hide(...)`]
+|xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_hide[`hide(...)`]
 |Hide all or some of an object's properties
 
-|xref:rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`]
+|xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`]
 |Provides the name of the image to render, usually alongside the title, to represent the object. If not provided, then the class name is used to locate an image. +
 
-See also xref:rgcms.adoc#_rgcms_methods_reserved_title[`title()`] and xref:rgcms.adoc#_rgcms_methods_reserved_cssClass[`cssClass()`]
+See also xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_title[`title()`] and xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_cssClass[`cssClass()`]
 
-|xref:rgcms.adoc#_rgcms_methods_reserved_title[`title()`]
+|xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_title[`title()`]
 |Provides a title for the object. +
 
-See also xref:rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`] and xref:rgcms.adoc#_rgcms_methods_reserved_cssClass[`cssClass()`]
+See also xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`] and xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_cssClass[`cssClass()`]
 
-|xref:rgcms.adoc#_rgcms_methods_reserved_validate[`validate()`]
+|xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_validate[`validate()`]
 |Validate the object's state prior to persisting.
 
 |===

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_cssClass.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_cssClass.adoc
index 9bd36a2..12ac2eb 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_cssClass.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_cssClass.adoc
@@ -10,7 +10,7 @@ The `cssClass()` returns a CSS class for a particular object instance.
 
 The xref:ugvw.adoc#[Wicket viewer] wraps the object's representation in a containing `<div>` with the class added.  This is done both for rendering the object either in a table or when rendering the object on its own page.
 
-In conjunction with xref:rgcfg.adoc#_rgcfg_application-specific_application-css[`application.css`], can therefore provide custom styling of an object instance wherever it is rendered. +
+In conjunction with xref:../rgcfg/rgcfg.adoc#_rgcfg_application-specific_application-css[`application.css`], can therefore provide custom styling of an object instance wherever it is rendered. +
 
 
 For example, the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] uses this technique to add a strikethrough for completed todo items.  This is shown on the home page:
@@ -30,7 +30,7 @@ public class ToDoItem ... {
 }
 ----
 
-In the xref:rgcfg.adoc#_rgcfg_application-specific_application-css[application.css], the following styles were then added:
+In the xref:../rgcfg/rgcfg.adoc#_rgcfg_application-specific_application-css[application.css], the following styles were then added:
 
 [source,css]
 ----
@@ -43,4 +43,4 @@ tr.done {
 ----
 
 
-See also xref:rgcms.adoc#_rgcms_methods_reserved_title[`title()`] and xref:rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`].
+See also xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_title[`title()`] and xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`].

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_disable.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_disable.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_disable.adoc
index 35ff008..765062b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_disable.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_disable.adoc
@@ -7,7 +7,7 @@
 
 One use case that Apache Isis supports is that of a domain object with a lifecycle whereby at some stage it should become immutable: all its properties/collections should be disabled, and/or its actions become not invokable.
 
-It would be painful to have to write a separate xref:rgcms.adoc#_rgcms_methods_prefixes_disable[`disable...()`] method for each and every member, so instead Isis allows a single `disable...(...)` method to be implemented that is applied to all members.
+It would be painful to have to write a separate xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_disable[`disable...()`] method for each and every member, so instead Isis allows a single `disable...(...)` method to be implemented that is applied to all members.
 
 The signature of the method is:
 
@@ -31,7 +31,7 @@ public String disable(Identifier.Type identifierType) {
 }
 ----
 
-See also the similar methods to xref:rgcms.adoc#_rgcms_methods_reserved_hide[`hide()`] object members en-masse.
+See also the similar methods to xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_hide[`hide()`] object members en-masse.
 
 
 == Alternatives

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_getId.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_getId.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_getId.adoc
index 7a6aa39..4d2d081 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_getId.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_getId.adoc
@@ -11,8 +11,8 @@ This value is used internally to generate a string representation of an service
 This can appear in several contexts, including:
 
 * as the value of `Bookmark#getObjectType()` and in the `toString()` value of `Bookmark`
- (see xref:rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`])
-* in the serialization of `OidDto` in the xref:rgcms.adoc#_rgcms_schema-cmd[command] and xref:rgcms.adoc#_rgcms_schema-ixn[interaction] schemas
+ (see xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`])
+* in the serialization of `OidDto` in the xref:../rgcms/rgcms.adoc#_rgcms_schema-cmd[command] and xref:../rgcms/rgcms.adoc#_rgcms_schema-ixn[interaction] schemas
 * in the URLs of the xref:ugvro.adoc#[RestfulObjects viewer]
 * in the URLs of the xref:ugvw.adoc#[Wicket viewer] (specifically, for bookmarked actions)
 
@@ -37,8 +37,8 @@ public class OrderMenu {
 
 The rules of precedence are:
 
-1. xref:rgant.adoc#_rgant_DomainService_objectType[`@DomainService#objectType()`]
-2. xref:rgcms.adoc#_rgcms_methods_reserved_getId[`getId()`]
+1. xref:../rgant/rgant.adoc#_rgant_DomainService_objectType[`@DomainService#objectType()`]
+2. xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_getId[`getId()`]
 3. The fully qualified class name.
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_hide.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_hide.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_hide.adoc
index c1da611..d23963c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_hide.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_hide.adoc
@@ -8,7 +8,7 @@
 
 One use case that Apache Isis supports is that of a domain object with a lifecycle whereby at some stage some number of the object's members should be hidden.  For example, for an object that at some stage is logically immutable, we might want to make all its properties/collections unmodifiable and hide all its actions.
 
-While we could write a separate xref:rgcms.adoc#_rgcms_methods_prefixes_hide[`hide...()`] method for each and every action, this could become painful.  So instead Isis allows a single `hide...(...)` method to be implemented that is applied to all members.
+While we could write a separate xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_hide[`hide...()`] method for each and every action, this could become painful.  So instead Isis allows a single `hide...(...)` method to be implemented that is applied to all members.
 
 The signature of the method is:
 
@@ -28,12 +28,12 @@ public boolean hide(Identifier.Type identifierType) {
 }
 ----
 
-See also the similar method to xref:rgcms.adoc#_rgcms_methods_reserved_disable[`disable()`] object members en-masse.
+See also the similar method to xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_disable[`disable()`] object members en-masse.
 
 
 == Alternatives
 
 An alternative design -- and one that could be easily argued is actually more flexible -- is to leverage domain events with vetoing subscribers.
 
-There is further discussion on this approach in xref:rgcms.adoc#_rgcms_methods_reserved_disable[here].
+There is further discussion on this approach in xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_disable[here].
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_iconName.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_iconName.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_iconName.adoc
index 3f235eb..9f5a97e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_iconName.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_iconName.adoc
@@ -33,4 +33,4 @@ public class ToDoItem ... {
 }
 ----
 
-See also xref:rgcms.adoc#_rgcms_methods_reserved_title[`title()`] and xref:rgcms.adoc#_rgcms_methods_reserved_cssClass[`cssClass()`]
+See also xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_title[`title()`] and xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_cssClass[`cssClass()`]

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_title.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_title.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_title.adoc
index f592ff0..bd64f0e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_title.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_title.adoc
@@ -40,17 +40,17 @@ public String title() {
     return buf.toString();
 }
 ----
-<1> simple xref:rgcms.adoc#_rgcms_classes_utility_TitleBuffer[tility class] to help construct the title string
+<1> simple xref:../rgcms/rgcms.adoc#_rgcms_classes_utility_TitleBuffer[tility class] to help construct the title string
 <2> imperative conditional logic
-<3> using the xref:rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`] to determine if the `dueBy` field is visible for this user ...
+<3> using the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`] to determine if the `dueBy` field is visible for this user ...
 <4> ... but ignore if not
 
 As the example above shows, the implementation can be as complex as you like.
 
-In many cases, though, you may be able to use the xref:rgant.adoc#_rgant-Title[`@Title`] annotation.
+In many cases, though, you may be able to use the xref:../rgant/rgant.adoc#_rgant-Title[`@Title`] annotation.
 
 
-See also xref:rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`] and xref:rgcms.adoc#_rgcms_methods_reserved_cssClass[`cssClass()`]
+See also xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`] and xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_cssClass[`cssClass()`]
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-aim.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-aim.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-aim.adoc
index 42bd442..bf80369 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-aim.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-aim.adoc
@@ -10,15 +10,15 @@ The "aim" schema defines the serialized form (or memento) of an action invocatio
 
 [WARNING]
 ====
-This schema has been removed in `1.13.0`, replaced with xref:rgcms.adoc#_rgcms_schema-ixn[ixn.xsd] (for action
-invocations/property edits) and with xref:rgcms.adoc#_rgcms_schema-cmd[cmd.xsd] (commands, ie the __intention__ to
+This schema has been removed in `1.13.0`, replaced with xref:../rgcms/rgcms.adoc#_rgcms_schema-ixn[ixn.xsd] (for action
+invocations/property edits) and with xref:../rgcms/rgcms.adoc#_rgcms_schema-cmd[cmd.xsd] (commands, ie the __intention__ to
 invoke an action/edit a property).
 
 The remaining content on this page describes how `CommandContext` works up to v1.12.x.  However, as of `1.13.0` the `CommandContext` uses its own `cmd.xsd` schema).
 ====
 
 Action invocations are captured (in memory rather than in serialized form) when the end-user invokes the action
-"through" the UI, by way of the xref:rgsvc.adoc#_rgsvc_api_CommandContext[CommandContext] service. Using the
+"through" the UI, by way of the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_CommandContext[CommandContext] service. Using the
 `ActionInvocationMementoDtoUtils` utility class, a service can instantiate `ActionInvocationMementoDto` which can then
 be serialized to/from using the same `ActionInvocationMementoDtoUtils` class.
 
@@ -83,12 +83,12 @@ be serialized to/from using the same `ActionInvocationMementoDtoUtils` class.
 </xs:schema>
 ----
 <1> the aim schema has a namespace URI of "http://isis.apache.org/schema/aim".  Although URIs are not the same as URLs, you will find that the schemas are also downloadable from this location.
-<2> reuses the xref:rgcms.adoc#_rgcms_schema-common[common] schema
+<2> reuses the xref:../rgcms/rgcms.adoc#_rgcms_schema-common[common] schema
 <3> definition of the `actionInvocationMementoDto` complex type. This consists of metadata (the transaction identifier, the target object, the initiating user) and the payload (the action parameter/arguments, the return value if known).
 <4> the unique transaction Id (a guid) allocated by the framework for each and every transaction
 <5> a sequence number within the transaction.  It is possible for there to be more than one action invocation to be
 <6> when the action was invoked
-<7> target object, as an OID (using `oidDto` from the xref:rgcms.adoc#_rgcms_schema-common[common] schema)
+<7> target object, as an OID (using `oidDto` from the xref:../rgcms/rgcms.adoc#_rgcms_schema-common[common] schema)
 <8> fully qualified class name of the target object, for information only
 <9> name of the action, for information only
 <10> Javadoc style unique identifier for the action.

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-chg.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-chg.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-chg.adoc
index 8901332..9f4bc7b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-chg.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-chg.adoc
@@ -11,8 +11,8 @@ updated or deleted as the result of invoking an action or editing a property.  I
 metrics counts (number of objects loaded, number of object properties modified), useful for profiling.
 
 An instance of the DTO (corresponding to this schema) is used within the
-xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] SPI, identifying changed objects that are to be
-published (as per xref:rgant.adoc#_rgant_DomainObject_publishing[`@DomainObject#publishing()`] or equivalent).
+xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] SPI, identifying changed objects that are to be
+published (as per xref:../rgant/rgant.adoc#_rgant_DomainObject_publishing[`@DomainObject#publishing()`] or equivalent).
 
 
 == `changesDto`
@@ -51,12 +51,12 @@ The `changesDto` root element is defined as:
 ----
 <1> the changes schema has a namespace URI of "http://isis.apache.org/schema/chg".  Although URIs are not the same as
 URLs, you will find that the schemas are also downloadable from this location.
-<2> uses complex types defined in the xref:rgcms.adoc#_rgcms_schema_common["common" schema].
+<2> uses complex types defined in the xref:../rgcms/rgcms.adoc#_rgcms_schema_common["common" schema].
 <3> definition of the `changesDto` root element.  The corresponding XML will use this as its top-level element.
 <4> each instance of this schema indicates the version of the schema it is compatible with (following semantic versioning)
 <5> unique identifier for the transaction in which this interaction is being executed.  The transaction Id is used to
-correlate back to the xref:rgcms.adoc#_rgcms_schema_command[command] that represented the intention to perform this
-execution, as well as to the xref:rgcms.adoc#_rgcms_schema_interaction[interaction] that executes said command.
+correlate back to the xref:../rgcms/rgcms.adoc#_rgcms_schema_command[command] that represented the intention to perform this
+execution, as well as to the xref:../rgcms/rgcms.adoc#_rgcms_schema_interaction[interaction] that executes said command.
 <6> uniquely identifies this set of changes within the interaction.  Can be combined with `transactionId` to create a
 unique identifier (across all other changed object events and also any interaction executions) of this particular set
 of changed objects.
@@ -93,5 +93,5 @@ metrics counters:
 <2> the identities of the objects that were, respectively, created, updated or deleted within the transaction.
 <3> the number of objects' properties changed, in total, by the interaction.
 
-The xref:rgcms.adoc#_rgcms_schema_ixn[interaction] schema also provides metrics on the number of objects loaded/changed,
+The xref:../rgcms/rgcms.adoc#_rgcms_schema_ixn[interaction] schema also provides metrics on the number of objects loaded/changed,
 but is more granular, each figure relating to a single (sub-)execution within an interaction.

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-cmd.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-cmd.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-cmd.adoc
index 2adcd16..4af6e86 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-cmd.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-cmd.adoc
@@ -51,12 +51,12 @@ The `commandDto` root element is defined as:
 ----
 <1> the command schema has a namespace URI of "http://isis.apache.org/schema/cmd".  Although URIs are not the same as
 URLs, you will find that the schemas are also downloadable from this location.
-<2> uses complex types defined in the xref:rgcms.adoc#_rgcms_schema_common["common" schema].
+<2> uses complex types defined in the xref:../rgcms/rgcms.adoc#_rgcms_schema_common["common" schema].
 <3> definition of the `commandDto` root element.  The corresponding XML will use this as its top-level element.
 <4> each instance of this schema indicates the version of the schema it is compatible with (following semantic versioning)
 <5> unique identifier for the transaction in which this command is created.  The transaction Id is used to correlate
-to the xref:rgcms.adoc#_rgcms_schema_interaction[interaction] that executes the command, and to any
-xref:rgcms.adoc#_rgcms_schema_changes[changes] to domain objects occurring as a side-effect of that interaction.
+to the xref:../rgcms/rgcms.adoc#_rgcms_schema_interaction[interaction] that executes the command, and to any
+xref:../rgcms/rgcms.adoc#_rgcms_schema_changes[changes] to domain objects occurring as a side-effect of that interaction.
 <6> the name of the user who created the command (whose intention it is to invoke the action/edit the property).
 <7> the target object (or objects) to be invoked.  As of `1.13.0`, a bulk action will create multiple commands,
 each with only a single target, but a future version of the framework may also support a single bulk command against
@@ -110,11 +110,11 @@ property.  The `actionDto` and `propertyDto` are the concrete subtypes:
 property).
 <2> the `interactionType` attribute indicates whether the member is an action or a property.
 <3> the `actionDto` complex type captures the set of parameters (also including the argument values) with which to
-invoke the action.  The `paramsDto` type is defined xref:rgcms.adoc#__rgcms_schema-cmd_ancillary[below].
+invoke the action.  The `paramsDto` type is defined xref:../rgcms/rgcms.adoc#__rgcms_schema-cmd_ancillary[below].
 <4> the `propertyDto` complex type captures the new value (possibly `null`) to set the property to.
 
 
-Note also that there is a corresponding xref:rgcms.adoc#__rgcms_schema-ixn_memberExecutionDto[`memberExecutionDto`]
+Note also that there is a corresponding xref:../rgcms/rgcms.adoc#__rgcms_schema-ixn_memberExecutionDto[`memberExecutionDto`]
 complex type in the "ixn" schema that is for the actual execution (capturing metrics about its execution and also the
 return value if an action invocation).
 
@@ -147,4 +147,4 @@ The schema also defines a small number of supporting types:
 <1> the `paramsDto` is simply the list of parameter/arguments.
 <2> the `paramDto` complex type essentially combines a parameter with its corresponding argument: a named value that
 has a type.  It extends the `valueWithTypeDto` complex type taken from the
-xref:rgcms.adoc#_rgcms_schema-common["common"] schema.
+xref:../rgcms/rgcms.adoc#_rgcms_schema-common["common"] schema.

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-common.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-common.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-common.adoc
index 9191358..d3411a1 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-common.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-common.adoc
@@ -12,11 +12,11 @@ The "common" schema defines a number of complex types that are used by other hig
 == `oidDto`
 
 The `oidDto` complex type captures an object's type and its identifier.  This is basically a formal XML equivalent to
-the `Bookmark` object obtained from the xref:rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`].
+the `Bookmark` object obtained from the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`].
 
 Although simple, this is an enormously powerful concept, in that it represents a URI to any domain object managed by
 a given Apache Isis application.  With it, we have the ability to lookup any arbitrary object.  Further discussion and
-examples can be found xref:ugfun.adoc#__ugfun_core-concepts_building-blocks_oid[here].
+examples can be found xref:../ugfun/ugfun.adoc#__ugfun_core-concepts_building-blocks_oid[here].
 
 The `oidDto` complex type is defined as:
 
@@ -55,15 +55,15 @@ URLs, you will find that the schemas are also downloadable from this location.
 <2> the `oidDto` complex type defines the unique identifier for any domain object: its type, and an identifier.  The
 `objectState` attribute can usually be omitted (indicating a persistent object)
 <3> the object type, corresponding to either the
-xref:rgant.adoc#_rgant-DomainObject_objectType[`@DomainObject#objectType()`] attribute, or to the (JDO)
-xref:rgant.adoc#_rgant-PersistenceCapable[`@PersistenceCapable`] annotation (`schema` and/or `table`
-attributes), or to the (JDO) xref:rgant.adoc#_rgant-Discriminator[`@Discriminator`] annotation.  If none
+xref:../rgant/rgant.adoc#_rgant-DomainObject_objectType[`@DomainObject#objectType()`] attribute, or to the (JDO)
+xref:../rgant/rgant.adoc#_rgant-PersistenceCapable[`@PersistenceCapable`] annotation (`schema` and/or `table`
+attributes), or to the (JDO) xref:../rgant/rgant.adoc#_rgant-Discriminator[`@Discriminator`] annotation.  If none
 is specified, then the fully qualified class name will be used.
 <4> the object identifier (aka primary key), converted to string form.
 <5> the `bookmarkObjectState` enumerates the possible persistence states of the referenced object.  In previous versions
 of the schema the attribute was defaulted to "persistent"; the "persistent" state is assumed
 if the attribute is omitted.
-<6> Models a list of OIDs.  This is used by the xref:rgcms.adoc#_rgcms_schema_cmd["cmd" schema] to represent the
+<6> Models a list of OIDs.  This is used by the xref:../rgcms/rgcms.adoc#_rgcms_schema_cmd["cmd" schema] to represent the
 intention to perform a bulk actions (against a number of selected objects).
 
 In previous versions of the schema the object type and object identifers of `oidDto` were
@@ -72,17 +72,17 @@ modelled as an element rather than an attribute.  The element form can still be
 The `oidDto` complex type is used in a number of places by the framework:
 
 * first, as a means of serializing JAXB view model/DTOs (annotated with
-xref:rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`]), that reference domain entities. +
+xref:../rgant/rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`]), that reference domain entities. +
 +
 These references are serialized instead into OIDs
 
 * second, as references to the target of a command representing the _intention_ to invoke an action or edit a property,
-as described by the xref:rgcms.adoc#_rgcms_schema-cmd["cmd" (command)] schema. +
+as described by the xref:../rgcms/rgcms.adoc#_rgcms_schema-cmd["cmd" (command)] schema. +
 +
 They are also used to represent references to any action arguments/properties that take domain object entities/view models.
 
 * third, as references to the target of an interaction capturing the actual execution of an action invocation or
-property edit, as described by the xref:rgcms.adoc#_rgcms_schema-ixn["ixn" (interaction)] schema.
+property edit, as described by the xref:../rgcms/rgcms.adoc#_rgcms_schema-ixn["ixn" (interaction)] schema.
 
 
 [[__rgcms_schema-common_valueDto]]
@@ -139,7 +139,7 @@ invocations, and for the new value in property edits.
 
 
 These type definitions are just building blocks, also used within the
-xref:rgcms.adoc#_rgcms_schema-aim[action iInvocation memento] schema.  The first, `valueDto` is The second, `valueType`, enumerates the different types of vales, eg of a
+xref:../rgcms/rgcms.adoc#_rgcms_schema-aim[action iInvocation memento] schema.  The first, `valueDto` is The second, `valueType`, enumerates the different types of vales, eg of a
 formal parameter to an action.
 
 
@@ -148,7 +148,7 @@ formal parameter to an action.
 == Ancillary types
 
 The common schema also defines a number of ancillary types, used either by the common schema itself (see above) or by
-the xref:rgcms.adoc#_rgcms_schema_cmd["cmd"] and xref:rgcms.adoc#_rgcms_schema_ixn["ixn"] schemas.
+the xref:../rgcms/rgcms.adoc#_rgcms_schema_cmd["cmd"] and xref:../rgcms/rgcms.adoc#_rgcms_schema_ixn["ixn"] schemas.
 
 [source,xml]
 ----
@@ -187,5 +187,5 @@ the xref:rgcms.adoc#_rgcms_schema_cmd["cmd"] and xref:rgcms.adoc#_rgcms_schema_i
 <2> Captures a period of time, eg for capturing metrics/timings.
 <3> Captures a pair of numbers representing a difference.  Used for example to capture metrics (number objects modified before and after).
 <4> Whether this command/interaction with a member is invoking an action, or editing a property.  Used by both the
-xref:rgcms.adoc#_rgcms_schema_cmd["cmd"] and xref:rgcms.adoc#_rgcms_schema_ixn["ixn"] schemas.
+xref:../rgcms/rgcms.adoc#_rgcms_schema_cmd["cmd"] and xref:../rgcms/rgcms.adoc#_rgcms_schema_ixn["ixn"] schemas.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-ixn.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-ixn.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-ixn.adoc
index 16250ed..866a894 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-ixn.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-ixn.adoc
@@ -8,7 +8,7 @@
 
 The interaction ("ixn") schema defines the serialized form of an action invocation or a property
 edit.  In fact, it actually defines a call-graph of such executions for those cases where the
-xref:rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`] is used to execute sub-actions/property edits.
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`] is used to execute sub-actions/property edits.
 
 Each execution identifies the target object, the member to invoke, and the arguments.  It also captures metrics about
 the execution, and the result of the execution (eg return value of an action invocation).
@@ -57,13 +57,13 @@ The `interactionDto` root element is defined as:
 ----
 <1> the interaction schema has a namespace URI of "http://isis.apache.org/schema/ixn".  Although URIs are not the same as
 URLs, you will find that the schemas are also downloadable from this location.
-<2> uses complex types defined in the xref:rgcms.adoc#_rgcms_schema_common["common" schema] and also the
-xref:rgcms.adoc#_rgcms_schema_cmd["cmd" schema]
+<2> uses complex types defined in the xref:../rgcms/rgcms.adoc#_rgcms_schema_common["common" schema] and also the
+xref:../rgcms/rgcms.adoc#_rgcms_schema_cmd["cmd" schema]
 <3> definition of the `interactionDto` root element.  The corresponding XML will use this as its top-level element.
 <4> each instance of this schema indicates the version of the schema it is compatible with (following semantic versioning)
 <5> unique identifier for the transaction in which this interaction is being executed.  The transaction Id is used to
-correlate back to the xref:rgcms.adoc#_rgcms_schema_command[command] that represented the intention to perform this
-execution, as well as to any xref:rgcms.adoc#_rgcms_schema_changes[changes] to domain objects that occur as a side-effect
+correlate back to the xref:../rgcms/rgcms.adoc#_rgcms_schema_command[command] that represented the intention to perform this
+execution, as well as to any xref:../rgcms/rgcms.adoc#_rgcms_schema_changes[changes] to domain objects that occur as a side-effect
 of the interaction.
 <6> the top-level `memberExecutionDto`, defined below, either an action invocation or edit of a property.
 
@@ -76,7 +76,7 @@ The `InteractionDto` DTO corresponding to the `interactionDto` root element can
 == `memberExecutionDto`
 
 The `memberExecutionDto` complex type is an abstract type representing either the invocation an action or the editing
-of a property.  It corresponds to the xref:rgcms.adoc#__rgcms_schema-cmd_memberDto[`memberDto`] of the "cmd" schema;
+of a property.  It corresponds to the xref:../rgcms/rgcms.adoc#__rgcms_schema-cmd_memberDto[`memberDto`] of the "cmd" schema;
 some elements are copied directly:
 
 [source,xml]
@@ -111,13 +111,13 @@ some elements are copied directly:
 <2> uniquely identifies this execution within the transaction.  Can be combined with `transactionId` to create a unique
 identifier (across all other interaction executions and also changed objects events) of this particular interaction
 execution.
-<3> the target object, corresponding to one of the elements of the `targets` element of the xref:rgcms.adoc#__rgcms_schema-cmd_memberDto[`memberDto`]
-<4> the member identifier; corresponds to `memberIdentifier` of the `member` element of the xref:rgcms.adoc#__rgcms_schema-cmd_memberDto[`memberDto`]
-<5> the user executing the action invocation/property edit; corresponds to the `user` element of the xref:rgcms.adoc#__rgcms_schema-cmd_memberDto[`memberDto`]
+<3> the target object, corresponding to one of the elements of the `targets` element of the xref:../rgcms/rgcms.adoc#__rgcms_schema-cmd_memberDto[`memberDto`]
+<4> the member identifier; corresponds to `memberIdentifier` of the `member` element of the xref:../rgcms/rgcms.adoc#__rgcms_schema-cmd_memberDto[`memberDto`]
+<5> the user executing the action invocation/property edit; corresponds to the `user` element of the xref:../rgcms/rgcms.adoc#__rgcms_schema-cmd_memberDto[`memberDto`]
 <6> the current "human-friendly" title of the target object
-<7> the set of metrics captured for this execution, of type `metricsDto` defined xref:rgcms.adoc#__rgcms_schema-ixn_ancillary[below].
+<7> the set of metrics captured for this execution, of type `metricsDto` defined xref:../rgcms/rgcms.adoc#__rgcms_schema-ixn_ancillary[below].
 <8> if the action invocation/property edit threw an exception, then this is captured here.
-<9> if any sub-actions or sub-edits were performed via the xref:rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`], then these are captured in the `childExecutions` element.
+<9> if any sub-actions or sub-edits were performed via the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`], then these are captured in the `childExecutions` element.
 <10> the `interactionType` attribute indicates whether the member is an action or a property (similar attribute exists for the "cmd" schema).
 
 
@@ -154,13 +154,13 @@ The `actionInvocationDto` and `propertyEditDto` are the concrete subtypes:
 </xs:schema>
 ----
 <1> the `actionInvocationDto` inherits from `memberExecutionDto`.  It corresponds to the similar
-xref:rgcms.adoc#__rgcms_schema-cmd_memberDto[`actionDto`] complex type of the "cmd" schema
+xref:../rgcms/rgcms.adoc#__rgcms_schema-cmd_memberDto[`actionDto`] complex type of the "cmd" schema
 <2> the `parameters` element captures the parameter and argument values; for the top-level execution it is a direct
 copy of the corresponding `parameters` element of the `actionDto` complex type of the "cmd" schema.
 <3> the `returned` element captures the returned value (if not void).  It is not valid for both this element and the
 inherited `threw` element to both be populated.
 <4> the `propertyEditDto` inherits from `memberExecutionDto`.  It corresponds to the similar
-xref:rgcms.adoc#__rgcms_schema-cmd_memberDto[`propertyDto`] complex type of the "cmd" schema
+xref:../rgcms/rgcms.adoc#__rgcms_schema-cmd_memberDto[`propertyDto`] complex type of the "cmd" schema
 <5> the `newValue` element captures the new value; for the top-level execution it is a direct
 copy of the corresponding `newValue` element of the `propertyDto` complex type of the "cmd" schema.
 
@@ -204,5 +204,5 @@ to the database).  Together these metrics give an idea of the "size" of this  pa
 <3> the `exceptionDto` complex type defines a structure for capturing the stack trace of any exception that might occur
 in the course of invoking an action or editing a property.
 
-The xref:rgcms.adoc#_rgcms_schema_changes[changes] schema also provides metrics on the number of objects loaded/changed,
+The xref:../rgcms/rgcms.adoc#_rgcms_schema_changes[changes] schema also provides metrics on the number of objects loaded/changed,
 but relates to the entire interaction rather than just one (sub)execution of an interaction.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema.adoc
index 2a2c0ef..831dd26 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema.adoc
@@ -9,18 +9,18 @@ Most applications need to integrate with other apps in the enterprise.  To facil
 Apache Isis defines a number of standard XSD schemas:
 
 
-* the xref:rgcms.adoc#_rgcms_schema-cmd[command] schema, which captures the __intention__ of a user
+* the xref:../rgcms/rgcms.adoc#_rgcms_schema-cmd[command] schema, which captures the __intention__ of a user
 to invoke an action or edit a property
 
-* the xref:rgcms.adoc#_rgcms_schema-ixn[interaction execution] schema, which captures the actual execution of an action invocation/property edit
+* the xref:../rgcms/rgcms.adoc#_rgcms_schema-ixn[interaction execution] schema, which captures the actual execution of an action invocation/property edit
 
-* the xref:rgcms.adoc#_rgcms_schema-chg[changes] schema, which captures which objects have been
+* the xref:../rgcms/rgcms.adoc#_rgcms_schema-chg[changes] schema, which captures which objects have been
 created, updated or deleted as the result of an execution of an action invocation/property edit
 
-* the xref:rgcms.adoc#_rgcms_schema-aim[action memento invocation] schema (deprecated in `1.13.0`, replaced by
+* the xref:../rgcms/rgcms.adoc#_rgcms_schema-aim[action memento invocation] schema (deprecated in `1.13.0`, replaced by
 either "cmd" or "ixn"), which allows action invocations to be captured and reified.
 
-These each use XSD types defined by the xref:rgcms.adoc#_rgcms_schema-common[common schema] (most notably the `oidDto`
+These each use XSD types defined by the xref:../rgcms/rgcms.adoc#_rgcms_schema-common[common schema] (most notably the `oidDto`
 complex type which identifies a domain object).
 
 The (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] and

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/rgcms.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/rgcms.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/rgcms.adoc
index ba6e1ad..30372e9 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/rgcms.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/rgcms.adoc
@@ -10,10 +10,10 @@
 == Classes, Methods and Schema
 
 This reference guide lists and describes various elements of the the Apache Isis Programming Model, specifically
-reserved and prefix xref:rgcms.adoc#_rgcms_methods[methods] (such as `title()` and `validate...()`) and various utility and
-supporting xref:rgcms.adoc#_rgcms_classes[classes].
+reserved and prefix xref:../rgcms/rgcms.adoc#_rgcms_methods[methods] (such as `title()` and `validate...()`) and various utility and
+supporting xref:../rgcms/rgcms.adoc#_rgcms_classes[classes].
 
-It also describes the xref:rgcms.adoc#_rgcms_schema[XSD schema] defined by Apache Isis.  One use case is for the
+It also describes the xref:../rgcms/rgcms.adoc#_rgcms_schema[XSD schema] defined by Apache Isis.  One use case is for the
 JAXB serialization of view models.
 
 === Other Guides

[04/58] [abbrv] isis git commit: ISIS-1521: fixes xref links between guides

[da...@apache.org]

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_PublisherService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_PublisherService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_PublisherService.adoc
index 4e4a511..fa65e0e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_PublisherService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_PublisherService.adoc
@@ -12,14 +12,14 @@ link:http://activemq.apache.org/[ActiveMQ] with link:http://camel.apache.org[Cam
 
 An alternative use is for profiling: for each execution (action invocation/property edit) the framework captures
 metrics of the number of objects loaded or dirtied as the result of that execution.  If the
-xref:rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`] is used to call other objects then the metrics are captured
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`] is used to call other objects then the metrics are captured
 for each sub-execution.  The framework provides a default implementation, `PublisherServiceLogging`, that will log
-these execution graphs (in XML form, per the xref:rgcms.adoc#_rgcms_schema-ixn["ixn" schema]) to an SLF4J logger.
+these execution graphs (in XML form, per the xref:../rgcms/rgcms.adoc#_rgcms_schema-ixn["ixn" schema]) to an SLF4J logger.
 
 Only actions/properties/domain objects annotated for publishing (using
-xref:rgant.adoc#_rgant-Action_publishing[`@Action#publishing()`],
-xref:rgant.adoc#_rgant-Property_publishing[`@Property#publishing()`] or
-xref:rgant.adoc#_rgant-DomainObject_publishing[`@DomainObject#publishing()`]) are published.
+xref:../rgant/rgant.adoc#_rgant-Action_publishing[`@Action#publishing()`],
+xref:../rgant/rgant.adoc#_rgant-Property_publishing[`@Property#publishing()`] or
+xref:../rgant/rgant.adoc#_rgant-DomainObject_publishing[`@DomainObject#publishing()`]) are published.
 
 
 == SPI
@@ -37,9 +37,9 @@ public interface PublisherService {
 <2> to publish a set of changed objects.
 
 Each `Interaction.Execution` has an owning `Interaction`; this is the same object obtainable from
-xref:rgsvc.adoc#_rgsvc_spi_InteractionContext[`InteractionContext`].  Implementations that publish member executions
+xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_InteractionContext[`InteractionContext`].  Implementations that publish member executions
 can use `Interaction.Execution#getDto()` method to return a DTO (as per the
-xref:rgcms.adoc#_rgcms_schema-ixn["ixn" schema]) which can be converted into a serializable XML representation using
+xref:../rgcms/rgcms.adoc#_rgcms_schema-ixn["ixn" schema]) which can be converted into a serializable XML representation using
 the `InteractionDtoUtils` utility class.  The XML can either serialize a single execution, or can be a "deep"
  serialization of an execution and all sub-executions.
 
@@ -64,7 +64,7 @@ public interface PublishedObjects extends HasTransactionId, HasUsername {
 objects were changed.
 <2> inherited from `HasUsername`, is the user that initiated the transaction causing these objects to change
 <3> the time that this set of objects was collated (just before the completion of the transaction completes)..
-<4> returns a DTO (as per the xref:rgcms.adoc#_rgcms_schema-chg["chg" schema]) which can be converted into a
+<4> returns a DTO (as per the xref:../rgcms/rgcms.adoc#_rgcms_schema-chg["chg" schema]) which can be converted into a
 serializable XML representation can be obtained using the `ChangesDtoUtils` utility class.
 <5> metrics as to the number of objects loaded, created, updated or deleted and the number of object properties modified (in other words the "size" or "weight" of the transaction).
 
@@ -101,13 +101,13 @@ and monitoring the activity of subscribers of said message queues.
 == Usage
 
 To indicate that an action invocation should be published, annotate it with the
-xref:rgant.adoc#_rgant-Action_publishing[`@Action#publishing()`] annotation.
+xref:../rgant/rgant.adoc#_rgant-Action_publishing[`@Action#publishing()`] annotation.
 
 To indicate that an property edit should be published, annotate it with the
-xref:rgant.adoc#_rgant-Property_publishing[`@Property#publishing()`] annotation.
+xref:../rgant/rgant.adoc#_rgant-Property_publishing[`@Property#publishing()`] annotation.
 
 To indicate that a changed object should be published is to annotate it with the
-xref:rgant.adoc#_rgant-DomainObject_publishing[`@DomainObject#publishing()`] annotation.
+xref:../rgant/rgant.adoc#_rgant-DomainObject_publishing[`@DomainObject#publishing()`] annotation.
 
 
 
@@ -115,7 +115,7 @@ xref:rgant.adoc#_rgant-DomainObject_publishing[`@DomainObject#publishing()`] ann
 
 The (non-ASF) Isis addons' http://github.com/isisaddons/isis-module-publishmq[publishmq] module provides an
 implementation of this service. Assuming that an `AppManifest` is being used to
-xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then this can be activated by updating
+xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then this can be activated by updating
 the `pom.xml` and updating the `AppManifest#getModules()` method.
 
 The module also provide services that contribute to the UI.  If contributions are not required in the UI, these can be
@@ -133,7 +133,7 @@ This service supports two main use cases:
 +
 [NOTE]
 ====
-The xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`] also supports this use case, but
+The xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`] also supports this use case, but
 is deprecated: the `PublisherService` is intended as a replacement for `PublishingService`.
 ====
 
@@ -142,24 +142,24 @@ is deprecated: the `PublisherService` is intended as a replacement for `Publishi
 
 To support these use cases several other services are involved:
 
-* the xref:rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] is used to obtain the `Interaction` from which
+* the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] is used to obtain the `Interaction` from which
 the member executions are published.
 
-* the (internal) xref:rgfis.adoc#_rgfis_spi_ChangedObjectsServiceInternal[`ChangedObjectsServiceInternal`] domain
+* the (internal) xref:../rgfis/rgfis.adoc#_rgfis_spi_ChangedObjectsServiceInternal[`ChangedObjectsServiceInternal`] domain
 service is used to obtain the set of objects modified throughout the transaction
 
-* the (internal) xref:rgfis.adoc#_rgfis_spi_PublisherServiceInternal[`PublisherServiceInternal`] domain service filters
+* the (internal) xref:../rgfis/rgfis.adoc#_rgfis_spi_PublisherServiceInternal[`PublisherServiceInternal`] domain service filters
 these down to those changed objects that are also published (as per
-xref:rgant.adoc#_rgant-DomainObject_publishing[`@DomainObject#publishing()`]) and delegates to the `PublisherService`.
+xref:../rgant/rgant.adoc#_rgant-DomainObject_publishing[`@DomainObject#publishing()`]) and delegates to the `PublisherService`.
 
-* the xref:rgsvc.adoc#_rgsvc_api_MetricsService[`MetricsService`] is used to obtain the objects that are loaded
+* the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_MetricsService[`MetricsService`] is used to obtain the objects that are loaded
 throughout the transaction; this info is used in order to instantiate the `PublishedObjects` object passed through to
 the `PublisherService`.
 
-The xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] differs from the `PublisherService` in that it is
+The xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] differs from the `PublisherService` in that it is
 intended for fine-grained publish/subscribe for object-to-object interactions within an Apache Isis domain object
 model. The event propagation is strictly in-memory, and there are no restrictions on the object acting as the event;
 it need not be serializable, for example.  That said, it is possible to obtain a serialization of the action
 invocation/property edit causing the current event to be raised using
-xref:rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] domain service.
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] domain service.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_PublishingService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_PublishingService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_PublishingService.adoc
index 543d66e..7897e4f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_PublishingService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_PublishingService.adoc
@@ -11,7 +11,7 @@ The `PublishingService` API is intended for coarse-grained publish/subscribe for
 
 [WARNING]
 ====
-As of `1.13.0` this service is deprecated, replaced with xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`].
+As of `1.13.0` this service is deprecated, replaced with xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`].
 ====
 
 
@@ -30,9 +30,9 @@ public interface PublishingService {
     void setEventSerializer(EventSerializer eventSerializer);   // <3>
 }
 ----
-<1> standard metadata about the event, such as the user, the xref:rgcms.adoc#_rgcms_classes_mixins_HasTransactionId[`transactionId`], date/time etc
+<1> standard metadata about the event, such as the user, the xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins_HasTransactionId[`transactionId`], date/time etc
 <2> for published actions, an `EventPayloadForActionInvocation` (or subclass thereof); for published objects, an `EventPayloadForObjectChanged` (or subclass thereof)
-<3> injects in the xref:rgsvc.adoc#_rgsvc_spi_EventSerializer[`EventSerializer`] service.  This is deprecated because not every implementation is required to use an `EventSerializer` so its inclusion within the SPI of `PublishingService` was in retrospect a mistake.
+<3> injects in the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_EventSerializer[`EventSerializer`] service.  This is deprecated because not every implementation is required to use an `EventSerializer` so its inclusion within the SPI of `PublishingService` was in retrospect a mistake.
 
 
 Typically implementations will use the injected `EventSerializer` to convert the metadata and payload into a form to be published:
@@ -68,16 +68,16 @@ The framework provides no default implementations of this service.
 
 == Usage
 
-To indicate that an action invocation should be published, annotate it with the xref:rgant.adoc#_rgant-Action_publishing[`@Action#publishing()`] annotation.
+To indicate that an action invocation should be published, annotate it with the xref:../rgant/rgant.adoc#_rgant-Action_publishing[`@Action#publishing()`] annotation.
 
-To indicate that a changed object should be published is to annotate it with the xref:rgant.adoc#_rgant-DomainObject_publishing[`@DomainObject#publishing()`] annotation.
+To indicate that a changed object should be published is to annotate it with the xref:../rgant/rgant.adoc#_rgant-DomainObject_publishing[`@DomainObject#publishing()`] annotation.
 
 
 It is also possible to "fine-tune" the `EventPayload` using the `#publishingFactory()` attribute (for both annotations).  By default the `EventPayload` that is serialized identifies the object(s) being interacted with or changed, and in the case of the action invocation provides details of the action arguments and result (if any) of that action.  However, the payload does not (by default) include any information about the new state of these objects. It is therefore the responsibility of the subscriber to call back to Apache Isis to determine any information that has not been published.
 
 [NOTE]
 ====
-The replacement xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] does __not__ support the concept of "payload factories" (but is otherwise more flexible).
+The replacement xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] does __not__ support the concept of "payload factories" (but is otherwise more flexible).
 ====
 
 
@@ -155,7 +155,7 @@ There is no default implementation of this service provided by the core Apache I
 
 The (non-ASF) Isis addons' http://github.com/isisaddons/isis-module-publishing[publishing] module provides an
 implementation of this service. Assuming that an `AppManifest` is being used to
-xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then this can be activated by updating
+xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then this can be activated by updating
 the `pom.xml` and updating the `AppManifest#getModules()` method.
 
 The module also provides services that contribute to the UI.  If contributions are not required in the UI, these can be
@@ -170,29 +170,29 @@ xref:ugbtb.adoc#_ugbtb_decoupling_vetoing-visibility[vetoing subscriber].
 
 The `PublishingService` is intended for coarse-grained publish/subscribe for system-to-system interactions, from
 Apache Isis to some other system. Here the only events published are those that action invocations (for actions
-annotated with xref:rgant.adoc#_rgant-Action_publishing[`@Action#publishing()`]) and of changed objects (for objects
-annotated with xref:rgant.adoc#_rgant-DomainObject_publishing[`@DomainObject#publishing()`].
+annotated with xref:../rgant/rgant.adoc#_rgant-Action_publishing[`@Action#publishing()`]) and of changed objects (for objects
+annotated with xref:../rgant/rgant.adoc#_rgant-DomainObject_publishing[`@DomainObject#publishing()`].
 
-The xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] is intended as a replacement for this service.  The
+The xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] is intended as a replacement for this service.  The
 use case for `PublisherService` is the same: coarse-grained publishing of events for system-to-system interactions.  It
 is in most respects more flexible though: events are published both for action invocations (annotated with
-xref:rgant.adoc#_rgant-Action_publishing[`@Action#publishing()`]) and also for property edits (annotated with
-xref:rgant.adoc#_rgant-Property_publishing[`@Property#publishing()`].  It also publishes changed objects (for objects
-annotated with xref:rgant.adoc#_rgant-DomainObject_publishing[`@DomainObject#publishing()`]).  However, rather than
+xref:../rgant/rgant.adoc#_rgant-Action_publishing[`@Action#publishing()`]) and also for property edits (annotated with
+xref:../rgant/rgant.adoc#_rgant-Property_publishing[`@Property#publishing()`].  It also publishes changed objects (for objects
+annotated with xref:../rgant/rgant.adoc#_rgant-DomainObject_publishing[`@DomainObject#publishing()`]).  However, rather than
 publishing one event for every changed objects, it publishes a single event that identifies all objects created,
 updated or deleted.
 
 Another significant difference between `PublishingService` and `PublisherService` is in the content of the events
-themselves.  While the former uses the xref:rgsvc.adoc#_rgsvc_api_MementoService[`MementoService`] to create an
-ad-hoc serialization of the action being invoked, the latter uses the xref:rgcms.adoc#_rgcms_schema[DTOs/XML schemas]
+themselves.  While the former uses the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_MementoService[`MementoService`] to create an
+ad-hoc serialization of the action being invoked, the latter uses the xref:../rgcms/rgcms.adoc#_rgcms_schema[DTOs/XML schemas]
 as a formal specification of the nature of the interaction (action invocation, property edit or changed objects).
 
-The xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] meanwhile differs from both `PublishingService` and
-xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] in that it is intended for fine-grained
+The xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] meanwhile differs from both `PublishingService` and
+xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] in that it is intended for fine-grained
 publish/subscribe for object-to-object interactions within an Apache Isis domain object model. The event propagation
 is strictly in-memory, and there are no restrictions on the object acting as the event; it need not be serializable,
 for example.  (That said, it is possible to obtain a serialization of the action invocation/property edit causing the
-current event to be raised using xref:rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] domain service).
+current event to be raised using xref:../rgsvc/rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] domain service).
 
 
 == Design Notes

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_RoutingService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_RoutingService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_RoutingService.adoc
index ba96bd1..899f379 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_RoutingService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_RoutingService.adoc
@@ -18,7 +18,7 @@ of the implementation to figure out what the "owning" object might be.
 
 * if an action returns `null` or is `void`, then return some other "useful" object. +
 +
-For example, return the home page (eg as defined by the xref:rgant.adoc#_rgant-HomePage[`@HomePage`] annotation).
+For example, return the home page (eg as defined by the xref:../rgant/rgant.adoc#_rgant-HomePage[`@HomePage`] annotation).
 
 Currently the routing service is used only by the xref:ugvw.adoc#[Wicket viewer]; it is ignored by the xref:ugvro.adoc#[Restful Objects] viewer.
 
@@ -28,7 +28,7 @@ Currently the routing service is used only by the xref:ugvw.adoc#[Wicket viewer]
 Unlike most other domain services, the framework will check _all_ available implementations of
 `RoutingService` to return a route, rather than the first implementation found; in other words it uses the
 chain-of-responsibility pattern.  Services are called in the order defined by
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`]).  The route used will be the
+xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`]).  The route used will be the
 result of the first implementation checked that declares that it can provide a route.
 ====
 
@@ -55,11 +55,11 @@ public interface RoutingService {
 == Implementation
 
 The framework provides a default implementation - `RoutingServiceDefault` - which will always return the original object provided, or the home page
-if a `null` or `void` was provided.  It uses the xref:rgsvc.adoc#_rgsvc_api_HomePageProviderService[`HomePageProviderService`].
+if a `null` or `void` was provided.  It uses the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_HomePageProviderService[`HomePageProviderService`].
 
 There can be multiple implementations of `RoutingService` registered.  These are checked in turn (chain of responsibility
-pattern), ordered according to xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`]
-(as explained in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
+pattern), ordered according to xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`]
+(as explained in the xref:../rgsvc/rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
 The route from the first service that returns `true` from its `canRoute(...)` method will be used.
 
 
@@ -67,7 +67,7 @@ The route from the first service that returns `true` from its `canRoute(...)` me
 == Registering the Services
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis'
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis'
 default implementation of `RoutingService` service is automatically registered and injected (it is annotated with
 `@DomainService`) so no further configuration is required.
 
@@ -76,4 +76,4 @@ default implementation of `RoutingService` service is automatically registered a
 == Related Services
 
 The default implementation of this service uses the
-xref:rgsvc.adoc#_rgsvc_api_HomePageProviderService[`HomePageProviderService`].
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_HomePageProviderService[`HomePageProviderService`].

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_TableColumnOrderService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_TableColumnOrderService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_TableColumnOrderService.adoc
index 2594823..88fc095 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_TableColumnOrderService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_TableColumnOrderService.adoc
@@ -29,7 +29,7 @@ public interface TableColumnOrderService {
 <1> for the parent collection owned by the specified parent and collection Id, return the set of property ids in the same or other order.
 <2> for the standalone collection of the specified type, return the set of property ids in the same or other order, else return `null` if provides no reordering.
 
-There can be multiple implementations of `TableColumnOrderService` registered, ordered as per xref:rgant.adoc#_rgant_DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`].
+There can be multiple implementations of `TableColumnOrderService` registered, ordered as per xref:../rgant/rgant.adoc#_rgant_DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`].
 The ordering provided by the first such service that returns a non-`null` value will be used.
 If all provided implementations return `null`, then the framework will fallback to a default implementation.
 
@@ -43,7 +43,7 @@ The framework provides a fallback implementation of this service, namely `TableC
 == Registering the Services
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]), then the
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]), then the
  default implementation of `TableColumnOrderService` is automatically registered and injected, and no further
  configuration is required.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_TranslationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_TranslationService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_TranslationService.adoc
index b872352..451163c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_TranslationService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_TranslationService.adoc
@@ -61,14 +61,14 @@ For more details on the implementation, see xref:ugbtb.adoc#_ugbtb_i18n[i18n sup
 == Registering the Services
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
 implementation of `TranslationService` service (along with the supporting menu service) are automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
 
 If the menu items are not required then these can be suppressed either using security or by implementing a xref:ugbtb.adoc#_ugbtb_decoupling_vetoing-visibility[vetoing subscriber].
 
 To use an alternative implementation, use
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
+xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+in the xref:../rgsvc/rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
 
 
 
@@ -83,5 +83,5 @@ translations can be downloaded as a single file.
 
 == Related Services
 
-This service works in conjunction with xref:rgsvc.adoc#_rgsvc_spi_LocaleProvider[`LocaleProvider`] and xref:rgsvc.adoc#_rgsvc_spi_TranslationsResolver[`TranslationsResolver`] in order to provide i18n support.
+This service works in conjunction with xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_LocaleProvider[`LocaleProvider`] and xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_TranslationsResolver[`TranslationsResolver`] in order to provide i18n support.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_TranslationsResolver.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_TranslationsResolver.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_TranslationsResolver.adoc
index d050217..2c14678 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_TranslationsResolver.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_TranslationsResolver.adoc
@@ -6,7 +6,7 @@
 
 
 
-The `TranslationsResolver` service is one of the services that work together to implement Apache Isis' support for i18n, being used by Isis' default implementation of xref:rgsvc.adoc#_rgsvc_spi_TranslationService[`TranslationService`].
+The `TranslationsResolver` service is one of the services that work together to implement Apache Isis' support for i18n, being used by Isis' default implementation of xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_TranslationService[`TranslationService`].
 
 The role of the service itself is locate and return translations.
 
@@ -47,12 +47,12 @@ Currently there is no equivalent implementation for the xref:ugvro.adoc#[Restful
 == Registering the Service
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]), _and_ that the xref:ugvw.adoc#[Wicket viewer] is being used, then an implementation of `TranslationsResolver` is
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]), _and_ that the xref:ugvw.adoc#[Wicket viewer] is being used, then an implementation of `TranslationsResolver` is
 automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
 
 To use an alternative implementation, use
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
+xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+in the xref:../rgsvc/rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
 
 
 
@@ -62,6 +62,6 @@ in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to th
 == Related Services
 
 
-This service works in conjunction with xref:rgsvc.adoc#_rgsvc_spi_LocaleProvider[`LocaleProvider`] and xref:rgsvc.adoc#_rgsvc_spi_TranslationService[`TranslationService`] in order to provide i18n support.
+This service works in conjunction with xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_LocaleProvider[`LocaleProvider`] and xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_TranslationService[`TranslationService`] in order to provide i18n support.
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_UrlEncodingService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_UrlEncodingService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_UrlEncodingService.adoc
index ccd6cea..1f5efbc 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_UrlEncodingService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_UrlEncodingService.adoc
@@ -16,7 +16,7 @@ Defining this functionality as an SPI has two use cases:
 
 * first, (though some browsers support longer strings), there is a limit of 2083 characters for URLs.  For view model
 mementos that correspond to large strings (as might occur when serializing a JAXB
-xref:rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`]-annotated view model), the service provides a
+xref:../rgant/rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`]-annotated view model), the service provides a
 hook.  +
 +
 For example, each memento string could be mapped to a GUID held in some cluster-aware cache.
@@ -54,6 +54,6 @@ exceed 2083 characters.  For large view models, there's the possibility that thi
 cases register an alternative implementation of this service.
 
 To use an alternative implementation, use
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
+xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+in the xref:../rgsvc/rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_UserRegistrationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_UserRegistrationService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_UserRegistrationService.adoc
index ee41645..0c7fbe1 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_UserRegistrationService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_UserRegistrationService.adoc
@@ -7,7 +7,7 @@
 
 The `UserRegistrationService` provides the ability for users to sign-up to access an application by providing a valid email address, and also provides the capability for users to reset their password if forgotten.
 
-For user sign-up, the xref:ugvw.adoc#[Wicket viewer] will check whether an implementation of this service (and also the xref:rgsvc.adoc#_rgsvc_spi_EmailNotificationService[`EmailNotificationService`]) is available, and if so will render a sign-up page where the user enters their email address. A verification email is sent (using the aforementioned `EmailNotificationService`) which includes a link back to the running application; this allows the user then to complete their registration process (choose user name, password and so on). When the user has provided the additional details, the Wicket viewer calls _this_ service in order to create an account for them, and then logs the user on.
+For user sign-up, the xref:ugvw.adoc#[Wicket viewer] will check whether an implementation of this service (and also the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_EmailNotificationService[`EmailNotificationService`]) is available, and if so will render a sign-up page where the user enters their email address. A verification email is sent (using the aforementioned `EmailNotificationService`) which includes a link back to the running application; this allows the user then to complete their registration process (choose user name, password and so on). When the user has provided the additional details, the Wicket viewer calls _this_ service in order to create an account for them, and then logs the user on.
 
 For the password reset feature, the Wicket viewer will render a password reset page, and use the `EmailNotificationService` to send a "password forgotten" email.  This service provides the ability to reset a password based on the user's email address.
 
@@ -91,8 +91,8 @@ public class AppUserRegistrationService extends SecurityModuleAppUserRegistratio
 
 The most common use case is to allow users to sign-up through Apache Isis' Wicket viewer. Because the process requires email to be sent, the following services must be configured:
 
-* xref:rgsvc.adoc#_rgsvc_api_EmailService[`EmailService`]
-* xref:rgsvc.adoc#_rgsvc_spi_EmailNotificationService[`EmailNotificationService`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EmailService[`EmailService`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_EmailNotificationService[`EmailNotificationService`]
 * `UserRegistrationService` (this service)
 
-The `EmailService` in particular requires additional xref:rgcfg.adoc#_rgcfg_configuring-core[configuration properties] to specify the external SMTP service.
\ No newline at end of file
+The `EmailService` in particular requires additional xref:../rgcfg/rgcfg.adoc#_rgcfg_configuring-core[configuration properties] to specify the external SMTP service.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_testing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_testing.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_testing.adoc
index f4749bc..a035349 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_testing.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_testing.adoc
@@ -24,7 +24,7 @@ The table below summarizes the testing APIs defined by Apache Isis.  It also lis
 |Notes
 
 
-|xref:rgsvc.adoc#_rgsvc_api_ExecutionParametersService[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ExecutionParametersService[`o.a.i.applib.` +
 `fixturescripts.` +
 `ExecutionParametersService`]
 |...
@@ -34,39 +34,39 @@ The table below summarizes the testing APIs defined by Apache Isis.  It also lis
 |API is also a concrete class
 
 
-|xref:rgsvc.adoc#_rgsvc_api_FixtureScriptsDefault[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_api_FixtureScriptsDefault[`o.a.i.applib.` +
 `services.` +
 `fixturespec` +
 `FixtureScriptsDefault`]
-|Fallback implementation of xref:rgcms.adoc#_rgcms_classes_super_FixtureScripts[`FixtureScripts`], providing the ability to execute fixture scripts.
+|Fallback implementation of xref:../rgcms/rgcms.adoc#_rgcms_classes_super_FixtureScripts[`FixtureScripts`], providing the ability to execute fixture scripts.
 |`FixtureScriptsDefault` +
 ``o.a.i.core`` +
 ``isis-core-applib``
-|Interacts with xref:rgsvc.adoc#_rgsvc_spi_FixtureScriptsSpecificationProvider[`FixtureScripts-
+|Interacts with xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_FixtureScriptsSpecificationProvider[`FixtureScripts-
 SpecificationProvider`].
 
 
 
-|xref:rgsvc.adoc#_rgsvc_spi_FixtureScriptsSpecificationProvider[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_FixtureScriptsSpecificationProvider[`o.a.i.applib.` +
 `services.fixturespec` +
 `FixtureScripts-` +
 `SpecificationProvider`]
-|Provides settings for xref:rgsvc.adoc#_rgsvc_api_FixtureScriptsDefault[`FixtureScriptsDefault`] fallback domain service for executing fixture scripts.
+|Provides settings for xref:../rgsvc/rgsvc.adoc#_rgsvc_api_FixtureScriptsDefault[`FixtureScriptsDefault`] fallback domain service for executing fixture scripts.
 |
 |
 
 
-|xref:rgsvc.adoc#_rgsvc_api_SudoService[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_api_SudoService[`o.a.i.applib.` +
 `services.sudo` +
 `SudoService`]
-|For use in testing while running xref:rgcms.adoc#_rgcms_classes_super_FixtureScripts[fixture scripts], allows a block of code to run as a specified user account.
+|For use in testing while running xref:../rgcms/rgcms.adoc#_rgcms_classes_super_FixtureScripts[fixture scripts], allows a block of code to run as a specified user account.
 |`SudoServiceDefault` +
 ``o.a.i.core`` +
 ``isis-core-runtime``
 |API is also a concrete class
 
 
-|xref:rgsvc.adoc#_rgsvc_api_SwitchUserService[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_api_SwitchUserService[`o.a.i.applib.` +
 `fixtures.switchuser` +
 `SwitchUserServiceService`]
 |(deprecated)

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_contributions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_contributions.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_contributions.adoc
index 8922623..0adf9f3 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_contributions.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_contributions.adoc
@@ -20,7 +20,7 @@ singletons, whereas mixins are instantiated as required (by the framework) and t
 
 [NOTE]
 ====
-There's further useful information on contributed services in the reference guide, discussing the xref:rgant.adoc#_rgant-DomainService_nature[@DomainService#nature()] attribute, for the `NatureOfService.VIEW_CONTRIBUTIONS_ONLY` nature.
+There's further useful information on contributed services in the reference guide, discussing the xref:../rgant/rgant.adoc#_rgant-DomainService_nature[@DomainService#nature()] attribute, for the `NatureOfService.VIEW_CONTRIBUTIONS_ONLY` nature.
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_event-bus.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_event-bus.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_event-bus.adoc
index 5178bb9..9f866fc 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_event-bus.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_event-bus.adoc
@@ -4,7 +4,7 @@
 :_basedir: ../../
 :_imagesdir: images/
 
-NOTE: FIXME - see xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`], xref:rgant.adoc#_rgant-Action_domainEvent[`@Action#domainEvent()`], xref:rgant.adoc#_rgant-Property_domainEvent[`@Property#domainEvent()`], xref:rgant.adoc#_rgant-Collection_domainEvent[`@Collection#domainEvent()`], xref:rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`].
+NOTE: FIXME - see xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`], xref:../rgant/rgant.adoc#_rgant-Action_domainEvent[`@Action#domainEvent()`], xref:../rgant/rgant.adoc#_rgant-Property_domainEvent[`@Property#domainEvent()`], xref:../rgant/rgant.adoc#_rgant-Collection_domainEvent[`@Collection#domainEvent()`], xref:../rgsvc/rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`].
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_mixins.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_mixins.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_mixins.adoc
index f549e11..82069ba 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_mixins.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_mixins.adoc
@@ -20,7 +20,7 @@ Mixins (and contributions) allow dependency to be inverted, so that the dependen
 
 Both use cases are discussed below.
 
-Syntactically, a mixin is defined using either the xref:rgant.adoc#_rgant_Mixin[`@Mixin`] annotation or using xref:rgant.adoc#_rgant_DomainObject_nature[`@DomainObject#nature()`] attribute (specifying a nature of `Nature.MIXIN`).
+Syntactically, a mixin is defined using either the xref:../rgant/rgant.adoc#_rgant_Mixin[`@Mixin`] annotation or using xref:../rgant/rgant.adoc#_rgant_DomainObject_nature[`@DomainObject#nature()`] attribute (specifying a nature of `Nature.MIXIN`).
 
 
 == Contributed Collection
@@ -205,7 +205,7 @@ In other words, all of the following are allowed:
 * `public static class _Documents { ... }`
 * `public static class _documents { ... }`
 
-The reserved method name "$$" can also be changed using xref:rgant.adoc#_rgant_Mixin_method[`@Mixin#method()`] or xref:rgant.adoc#_rgant_DomainObject_mixinMethod[`@DomainObject#mixinMethod()`].
+The reserved method name "$$" can also be changed using xref:../rgant/rgant.adoc#_rgant_Mixin_method[`@Mixin#method()`] or xref:../rgant/rgant.adoc#_rgant_DomainObject_mixinMethod[`@DomainObject#mixinMethod()`].
 
 
 
@@ -221,7 +221,7 @@ dynamically.  If writing integration tests or fixtures, or (sometimes) just regu
 instantiate mixins directly.
 
 For this you can use the
-xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-creation-api[`DomainObjectContainer#mixin(...)`
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-creation-api[`DomainObjectContainer#mixin(...)`
 method.  For example:
 
 [source,java]
@@ -230,7 +230,7 @@ DocumentHolder_documents mixin = container.mixin(DocumentHolder_documents.class,
 ----
 
 The xref:ugtst.adoc#__ugtst_integ-test-support_bootstrapping_IntegrationTestAbstract[`IntegrationTestAbstract`] and
-xref:rgcms.adoc#_rgcms_classes_super_FixtureScript[`FixtureScript`] classes both provide a `mixin(...)` convenience
+xref:../rgcms/rgcms.adoc#_rgcms_classes_super_FixtureScript[`FixtureScript`] classes both provide a `mixin(...)` convenience
 method.
 
 
@@ -256,7 +256,7 @@ fundamental structure is changing is likely to remain a no-no.
 
 However, chances are that the structure of your domain objects (the data) will change much less rapidly than
 the behaviour of those domain objects.  Thus, it's the behaviour that you're most likely wanting to change while the
-app is still running.  If you move that behaviour out into xref:rgcms.adoc#_rgcms_classes_mixins[mixins] (or
+app is still running.  If you move that behaviour out into xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins[mixins] (or
 xref:ugbtb.adoc#_ugbtb_decoupling_contributions[contributed services]), then these can be reloaded happily.
 (When running in prototype mode), Apache Isis will automatically recreate the portion of the metamodel for any domain
 object as it is rendered.

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_pushing-changes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_pushing-changes.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_pushing-changes.adoc
index ec0aedc..d75d8ac 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_pushing-changes.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_pushing-changes.adoc
@@ -134,7 +134,7 @@ public class Department {
 --
 <1> maintain a count of the number of male ...
 <2> ... and female employees (getters and setters omitted)
-<3> the xref:rgcms.adoc#_rgcms_methods_prefixes_addTo[`addTo...()`] method increments the derived properties
-<4> the xref:rgcms.adoc#_rgcms_methods_prefixes_removeFrom[`removeFrom...()`] method similarly decrements the derived properties
+<3> the xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_addTo[`addTo...()`] method increments the derived properties
+<4> the xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_removeFrom[`removeFrom...()`] method similarly decrements the derived properties
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_vetoing-visibility.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_vetoing-visibility.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_vetoing-visibility.adoc
index 7681271..c012be3 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_vetoing-visibility.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_vetoing-visibility.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-NOTE: FIXME - a write-up of the "vetoing subscriber" design pattern, eg as described in the  xref:rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`]
+NOTE: FIXME - a write-up of the "vetoing subscriber" design pattern, eg as described in the  xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`]
 
 
 eg if included an addon such as auditing or security.

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_cmd-line.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_cmd-line.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_cmd-line.adoc
index 78c3da0..0781fa3 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_cmd-line.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_cmd-line.adoc
@@ -29,7 +29,7 @@ The class also supports a number of command line arguments:
 |`-m`
 |`--manifest`
 |FQCN
-|Fully qualified class name of the xref:rgcms.adoc#_rgcms_classes_super_AppManifest[`AppManifest`] to use to bootstrap the system. +
+|Fully qualified class name of the xref:../rgcms/rgcms.adoc#_rgcms_classes_super_AppManifest[`AppManifest`] to use to bootstrap the system. +
 
 This flag sets/overrides the `isis.appManifest` configuration property to the specified class name.
 
@@ -37,7 +37,7 @@ This flag sets/overrides the `isis.appManifest` configuration property to the sp
 |`-f`
 |`--fixture`
 |FQCN
-|Fully qualified class name of the fixture (extending xref:rgcms.adoc#_rgcms_classes_super_FixtureScript[`FixtureScript`]) to be run to setup data. +
+|Fully qualified class name of the fixture (extending xref:../rgcms/rgcms.adoc#_rgcms_classes_super_FixtureScript[`FixtureScript`]) to be run to setup data. +
 
 This flag sets/overrides the `isis.fixtures` configuration property to the specified class name, and also sets the `isis.persistor.datanucleus.install-fixtures` configuration property to `true` to instruct the JDO/DataNucleus objectstore to actually load in the fixtures. +
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_docker.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_docker.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_docker.adoc
index d65f7a1..dc84356 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_docker.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_docker.adoc
@@ -21,7 +21,7 @@ Docker host can be assured.
 == Using an `overrides.properties` file
 
 In addition to loading the regular configuration properties from `WEB-INF` directory (described
-xref:rgcfg.adoc#_rgcfg_configuration-files[here]), Apache Isis will also load the `overrides.properties` file.
+xref:../rgcfg/rgcfg.adoc#_rgcfg_configuration-files[here]), Apache Isis will also load the `overrides.properties` file.
 
 This file is treated slightly differently than the other configuration files; it is loaded last, and any configuration
 properties defined in it will _override_ any configuration properties already read from other files (this includes

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_externalized-configuration.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_externalized-configuration.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_externalized-configuration.adoc
index 8a51a12..ddf5cf9 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_externalized-configuration.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_externalized-configuration.adoc
@@ -6,7 +6,7 @@
 
 
 
-As described xref:rgcfg.adoc#_rgcfg_configuration-files[here], by default Apache Isis itself bootstraps from the
+As described xref:../rgcfg/rgcfg.adoc#_rgcfg_configuration-files[here], by default Apache Isis itself bootstraps from the
 `isis.properties` configuration file.  It will also read configuration from the (optional)
 component/implementation-specific configuration files (such as
 `persistor_datanucleus.properties` or `viewer_wicket.properties`), and also (optional) component-specific configuration

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_neo4j.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_neo4j.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_neo4j.adoc
index d83805e..c3c450d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_neo4j.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_neo4j.adoc
@@ -6,7 +6,7 @@
 
 As of 1.8.0 Apache Isis has experimental support for Neo4J, courtesy of DataNucleus' http://www.datanucleus.org/products/datanucleus/datastores/neo4j.html[Neo4J Datastore] implementation.
 
-The xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] has been updated so that they can be optionally run under Neo4J.
+The xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] has been updated so that they can be optionally run under Neo4J.
 
 [TIP]
 ====
@@ -44,13 +44,13 @@ Add the following dependency to the `webapp` project's `pom.xml`:
 ----
 <1> for Isis v1.9.0, use the value shown.  for Isis v1.8.0, use 3.2.3.
 
-In the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] this is defined under the "neo4j" profile so can be activated using `-P neo4j`.
+In the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] this is defined under the "neo4j" profile so can be activated using `-P neo4j`.
 
 == Try it out!
 
 If you want to quickly try out neo4j for yourself:
 
-* run the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] (v1.8.0)
+* run the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] (v1.8.0)
 
 * build the app:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_tomcat.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_tomcat.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_tomcat.adoc
index 684d8a0..9d563ac 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_tomcat.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_tomcat.adoc
@@ -14,7 +14,7 @@ See the guidance xref:ugbtb.adoc#_ugbtb_deployment_externalized-configuration[be
 
 == JVM Args
 
-The xref:rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`] uses link:http://www.javassist.org[Javassist] to create on-the-fly classes acting as a proxy.  The cost of these proxies can be mitigated using:
+The xref:../rgsvc/rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`] uses link:http://www.javassist.org[Javassist] to create on-the-fly classes acting as a proxy.  The cost of these proxies can be mitigated using:
 
 [source,ini]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_headless-access.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_headless-access.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_headless-access.adoc
index db8db4d..5918c12 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_headless-access.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_headless-access.adoc
@@ -16,7 +16,7 @@ There are several main use-cases:
 
 Note that the calling thread runs in the same process space as the Apache Isis domain object model (must be physically linked to the JAR files containing the domain classes).  For use cases where the calling thread runs in some other process space (eg migrating data from a legacy system), then the xref:ugvro.adoc#[Restful Objects viewer] is usually the way to go.
 
-The API described in this chapter is reasonably low-level, allowing code to interact very directly with the Apache Isis metamodel and runtime.  Such callers should be considered trusted: they do not (by default) honour any business rules eg implicit in the Isis annotations or hide/disable/validate methods.  However the xref:rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`] service could be used to enforce such business rules if required.
+The API described in this chapter is reasonably low-level, allowing code to interact very directly with the Apache Isis metamodel and runtime.  Such callers should be considered trusted: they do not (by default) honour any business rules eg implicit in the Isis annotations or hide/disable/validate methods.  However the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`] service could be used to enforce such business rules if required.
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_headless-access_BackgroundCommandExecution.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_headless-access_BackgroundCommandExecution.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_headless-access_BackgroundCommandExecution.adoc
index a3a0e1c..2562892 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_headless-access_BackgroundCommandExecution.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_headless-access_BackgroundCommandExecution.adoc
@@ -6,7 +6,7 @@
 
 
 
-The `BackgroundCommandExecution` class (a subclass of xref:ugbtb.adoc#_ugbtb_headless-access_AbstractIsisSessionTemplate[AbstractIsisSessionTemplate]) is intended to simplify the execution of background ``Command``s persisted by way of the xref:rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] and the xref:rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[`BackgroundCommandService`].
+The `BackgroundCommandExecution` class (a subclass of xref:ugbtb.adoc#_ugbtb_headless-access_AbstractIsisSessionTemplate[AbstractIsisSessionTemplate]) is intended to simplify the execution of background ``Command``s persisted by way of the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] and the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[`BackgroundCommandService`].
 
 Its signature is:
 
@@ -34,9 +34,9 @@ image::{_imagesdir}headless-access/BackgroundCommandExecution.png[width="400px"]
 
 == Background Execution
 
-The `BackgroundCommandExecutionFromBackgroundCommandServiceJdo` is a concrete subclass of `BackgroundCommandExecution` (see the xref:rgsvc.adoc#_rgsvc_api_BackgroundService[`BackgroundCommandService`]), the intended use being for the class to be instantiated regularly (eg every 10 seconds) by a scheduler such as http://quartz-scheduler.org[Quartz]) to poll for ``Command``s to be executed, and then execute them.
+The `BackgroundCommandExecutionFromBackgroundCommandServiceJdo` is a concrete subclass of `BackgroundCommandExecution` (see the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BackgroundService[`BackgroundCommandService`]), the intended use being for the class to be instantiated regularly (eg every 10 seconds) by a scheduler such as http://quartz-scheduler.org[Quartz]) to poll for ``Command``s to be executed, and then execute them.
 
-This implementation queries for ``Command``s persisted by the link:http://www.isisaddons.org/isis-module-command[Isis addons Command Module]'s  implementations of xref:rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] and xref:rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[`BackgroundCommandService`] using the `BackgroundCommandServiceJdoRepository`.
+This implementation queries for ``Command``s persisted by the link:http://www.isisaddons.org/isis-module-command[Isis addons Command Module]'s  implementations of xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] and xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[`BackgroundCommandService`] using the `BackgroundCommandServiceJdoRepository`.
 
 The diagram below (link:http://yuml.me/edit/25343da1[yuml.me/25343da1]) shows the inheritance hierarchy for this class:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_i18n.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_i18n.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_i18n.adoc
index af8367d..a81a2d8 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_i18n.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_i18n.adoc
@@ -7,7 +7,7 @@
 
 Apache Isis' support for internationlization (i18n) allows every element of the domain model (the class names, property names, action names, parameter names and so forth) to be translated.
 
-It also supports translations of messages raised imperatively, by which we mean as the result of a call to `title()` to obtain an object's title, or messages resulting from any business rule violations (eg xref:rgcms.adoc#_rgcms_methods_prefixes_disable[`disable...()`] or xref:rgcms.adoc#_rgcms_methods_prefixes_validate[`validate...()`], and so on.
+It also supports translations of messages raised imperatively, by which we mean as the result of a call to `title()` to obtain an object's title, or messages resulting from any business rule violations (eg xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_disable[`disable...()`] or xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_validate[`validate...()`], and so on.
 
 The xref:ugvw.adoc#[Wicket viewer] (that is, its labels and messages) is also internationalized using the same mechanism.  If no translations are available, then the Wicket viewer falls back to using Wicket resource bundles.
 
@@ -93,8 +93,8 @@ If however the service is configured to run in write mode, then it instead recor
 
 To make the service as convenient as possible to use, the service configures itself as follows:
 
-* if running in prototype mode xref:rgcfg.adoc#_rgcfg_deployment-types[deployment type] or during integration tests, then the service runs in *write* mode, in which case it records all translations into the `.pot` file.  The `.pot` file is written out when the system is shutdown.
-* if running in server (production) mode xref:rgcfg.adoc#_rgcfg_deployment-types[deployment type], then the service runs in *read* mode. It is also possible to set a configuration setting in `isis.properties` to force read mode even if running in prototype mode (useful to manually test/demo the translations).
+* if running in prototype mode xref:../rgcfg/rgcfg.adoc#_rgcfg_deployment-types[deployment type] or during integration tests, then the service runs in *write* mode, in which case it records all translations into the `.pot` file.  The `.pot` file is written out when the system is shutdown.
+* if running in server (production) mode xref:../rgcfg/rgcfg.adoc#_rgcfg_deployment-types[deployment type], then the service runs in *read* mode. It is also possible to set a configuration setting in `isis.properties` to force read mode even if running in prototype mode (useful to manually test/demo the translations).
 
 When running in write mode the original text is returned to the caller untranslated. If in read mode, then the translated `.po` files are read and translations provided as required.
 
@@ -114,7 +114,7 @@ However, for an application to be fully internationalized, any validation messag
 
 The first part of the puzzle is tackled by an extension to Apache Isis' programming model.  Whereas previously the `disableXxx()` / `validateXxx()` / `title()` methods could only return a `java.lang.String`, they may now optionally return a `TranslatableString` (defined in Isis applib) instead.
 
-Here's a (silly) example from the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]:
+Here's a (silly) example from the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]:
 
 [source,java]
 ----
@@ -179,7 +179,7 @@ msgstr "Ich heisse {firstName} {lastName}."
 then the translation would be: "Ich heisse James Bond".
 
 
-The same class is used in xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`] so that you can raise translatable info, warning and error messages; each of the relevant methods are overloaded.
+The same class is used in xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`] so that you can raise translatable info, warning and error messages; each of the relevant methods are overloaded.
 
 For example:
 
@@ -199,7 +199,7 @@ public interface DomainObjectContainer {
 
 === `TranslatableException`
 
-Another mechanism by which messages can be rendered to the user are as the result of exception messages thrown and recognized by an xref:rgsvc.adoc#_rgsvc_spi_ExceptionRecognizer[`ExceptionRecognizer`].
+Another mechanism by which messages can be rendered to the user are as the result of exception messages thrown and recognized by an xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ExceptionRecognizer[`ExceptionRecognizer`].
 
 In this case, if the exception implements `TranslatableException`, then the message will automatically be translated before being rendered.  The `TranslatableException` itself takes the form:
 
@@ -520,7 +520,7 @@ To ensure your app is fully internationalized app, you must therefore:
 ====
 We make no apologies for this requirement: one of the reasons that we decided to implement Apache Isis' i18n support in this way is because it encourages/requires the app to be properly tested.
 
-Behind the scenes Apache Isis uses a JUnit rule (`ExceptionRecognizerTranslate`) to intercept any exceptions that are thrown.  These are simply passed through to the registered xref:rgsvc.adoc#_rgsvc_spi_ExceptionRecognizer[`ExceptionRecognizer`]s so that any messages are recorded as requiring translation.
+Behind the scenes Apache Isis uses a JUnit rule (`ExceptionRecognizerTranslate`) to intercept any exceptions that are thrown.  These are simply passed through to the registered xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ExceptionRecognizer[`ExceptionRecognizer`]s so that any messages are recorded as requiring translation.
 ====
 
 
@@ -541,7 +541,7 @@ msgstr "<i>Quantit�</i>"
 
 For this to work, the `namedEscaped()` attribute must be specified using either the
 xref:ugvw.adoc#_ugvw_layout_file-based[layout file], or using an annotation such as
-xref:rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`] or xref:rgant.adoc#_rgant-ParameterLayout[`@ParameterLayout`].
+xref:../rgant/rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`] or xref:../rgant/rgant.adoc#_rgant-ParameterLayout[`@ParameterLayout`].
 
 For example:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_persisted-title.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_persisted-title.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_persisted-title.adoc
index dc088f0..d04a082 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_persisted-title.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_persisted-title.adoc
@@ -8,7 +8,7 @@
 
 Normally the title of an object is not persisted to the database, rather it is recomputed automatically from underlying properties.  On occasion though you might want the title to also be persisted; either to make things easier for the DBA, or for an integration scenario, or some other purpose.
 
-We can implement this feature by leveraging the xref:rgcms.adoc#_rgcms_methods_lifecycle_jdo-api[JDO lifecycle].  In the design we discuss here we make it a responsibility of the entities to persist the title as a property, by implementing a `ObjectWithPersistedTitle` interface:
+We can implement this feature by leveraging the xref:../rgcms/rgcms.adoc#_rgcms_methods_lifecycle_jdo-api[JDO lifecycle].  In the design we discuss here we make it a responsibility of the entities to persist the title as a property, by implementing a `ObjectWithPersistedTitle` interface:
 
 [source,java]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_replacing-default-service-implementations.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_replacing-default-service-implementations.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_replacing-default-service-implementations.adoc
index 8d6b502..e3d29af 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_replacing-default-service-implementations.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_replacing-default-service-implementations.adoc
@@ -6,11 +6,11 @@
 
 
 
-The framework provides default implementations for many of the xref:rgsvc.adoc[domain services].  This is convenient, but sometimes you will want to replace the default implementation with your own service implementation.
+The framework provides default implementations for many of the xref:../rgsvc/rgsvc.adoc[domain services].  This is convenient, but sometimes you will want to replace the default implementation with your own service implementation.
 
-The trick is to use the xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] attribute, specifying a low number (typically `"1"`).
+The trick is to use the xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] attribute, specifying a low number (typically `"1"`).
 
-For example, suppose you wanted to provide your own implementation of xref:rgsvc.adoc#_rgsvc_api_LocaleProvider[`LocaleProvider`].  Here's how:
+For example, suppose you wanted to provide your own implementation of xref:../rgsvc/rgsvc.adoc#_rgsvc_api_LocaleProvider[`LocaleProvider`].  Here's how:
 
 [source,java]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_transactions-and-errors.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_transactions-and-errors.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_transactions-and-errors.adoc
index 9516f0f..85ed7f6 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_transactions-and-errors.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_transactions-and-errors.adoc
@@ -9,12 +9,12 @@ and any repository query automatically does a flush before hand.
 
 What that means is that there's no need to explicitly start or commit transactions in Apache Isis; this will be done
 for you. Indeed, if you do try to manage transactions (eg by reaching into the JDO `PersistenceManager` exposed by the
-xref:rgsvc.adoc#_rgsvc_api_IsisJdoSupport[IsisJdoSupport] domain service, then you are likely to confuse the
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_IsisJdoSupport[IsisJdoSupport] domain service, then you are likely to confuse the
 framework and get a stack trace for your trouble.
 
 However, you can complete a given transaction and start a new one.  This is sometimes useful if writing a fixture
 script which is going to perform some sort of bulk migration of data from an old system.  For this use case, use the
-xref:rgsvc.adoc#_rgsvc_api_TransactionService[`TransactionService`].
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_TransactionService[`TransactionService`].
 
 For example:
 
@@ -40,7 +40,7 @@ You get the idea.
 
 == Raise message/errors to users
 
-The framework provides the xref:rgsvc.adoc#_rgsvc_api_MessageService[`MessageService`] as a means to return an out-of-band
+The framework provides the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_MessageService[`MessageService`] as a means to return an out-of-band
 message to the end-user.  In the xref:ugvw.adoc#[Wicket viewer] these are shown as "toast" pop-ups; the
 xref:ugvro.adoc#[Restful Objects viewer] returns an HTTP header.
 
@@ -70,7 +70,7 @@ Another way in which exceptions might be considered "expected" could be as the r
 object which then violates some type of database constraint.  Even if the domain application checks beforehand, it
 could be that another user operating on the object at the same moment of time might result in the conflict.
 
-To handle this the xref:rgsvc.adoc#_rgsvc_spi_ExceptionRecognizer[`ExceptionRecognizer`] SPI can be used.  The
+To handle this the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ExceptionRecognizer[`ExceptionRecognizer`] SPI can be used.  The
 framework provides a number of implementations out-of-the-box; whenever an exception is thrown it is passed to each
 known recognizer implementation to see if it recognizes the exception and can return a user-meaningful error message.
 For example, `ExceptionRecognizerForSQLIntegrityConstraintViolationUniqueOrIndexException` checks if the

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_programming-model_custom-validator.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_programming-model_custom-validator.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_programming-model_custom-validator.adoc
index b74e7f8..3001a4a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_programming-model_custom-validator.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_programming-model_custom-validator.adoc
@@ -10,14 +10,14 @@ For example, the validator will detect any orphaned supporting methods (eg `hide
 
 [NOTE]
 ====
-The support for xref:rgant.adoc#_rgant-aaa_deprecated[disallowing deprecated annotations] is also implemented using the metamodel validator.
+The support for xref:../rgant/rgant.adoc#_rgant-aaa_deprecated[disallowing deprecated annotations] is also implemented using the metamodel validator.
 ====
 
 You can also impose your own application-specific rules by installing your own metamodel validator.  To give just one example, you could impose naming standards such as ensuring that a domain-specific abbreviation such as "ISBN" is always consistently capitalized wherever it appears in a class member.
 
 [TIP]
 ====
-Isis' xref:rgmvn.adoc[Maven plugin] will also validate the domain object model during build time.
+Isis' xref:../rgmvn/rgmvn.adoc[Maven plugin] will also validate the domain object model during build time.
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_jaxb.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_jaxb.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_jaxb.adoc
index 32f9853..00ae0b6 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_jaxb.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_jaxb.adoc
@@ -15,8 +15,8 @@ In fact, these JAXB-annotated view models are in many regards the most powerful
 
 * their entire state (collections as well as properties) is automatically managed from interaction to interaction. +
 +
-In contrast, using xref:rgant.adoc#_rgant-ViewModel[`@ViewModel`] (or its xref:rgant.adoc#_rgant-DomainObject_nature[`@DomainObject#nature()`] equivalent) will only manage the state of properties, but not collections.
-And if using the xref:rgcms.adoc#_rgcms_classes_super_ViewModel[`ViewModel`] interface, then the programmer must write all the state management (lots of boilerplate).
+In contrast, using xref:../rgant/rgant.adoc#_rgant-ViewModel[`@ViewModel`] (or its xref:../rgant/rgant.adoc#_rgant-DomainObject_nature[`@DomainObject#nature()`] equivalent) will only manage the state of properties, but not collections.
+And if using the xref:../rgcms/rgcms.adoc#_rgcms_classes_super_ViewModel[`ViewModel`] interface, then the programmer must write all the state management (lots of boilerplate).
 
 * JAXB-annotated view models are editable.
 
@@ -62,7 +62,7 @@ public class ToDoItemV1_1 implements Dto {                          // <5>
 <1> package name encodes major version; see discussion on xref:ugbtb.adoc#__ugbtb_view-models_jaxb_versioning[versioning]
 <2> identifies this class as a view model and defines the root element for JAXB serialization
 <3> all properties in the class must be listed; (they can be ignored using `@XmlTransient`)
-<4> demonstrating use of UI events for a subscriber to provide the DTO's title; see xref:rgant.adoc#_rgant-DomainObjectLayout_titleUiEvent[`@DomainObjectLayout#titleUiEvent()`].
+<4> demonstrating use of UI events for a subscriber to provide the DTO's title; see xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_titleUiEvent[`@DomainObjectLayout#titleUiEvent()`].
 <5> class name encodes (major and) minor version; see discussion on xref:ugbtb.adoc#__ugbtb_view-models_jaxb_versioning[versioning]
 <6> again, see discussion on xref:ugbtb.adoc#__ugbtb_view-models_jaxb_versioning[versioning]
 <7> again, see discussion on xref:ugbtb.adoc#__ugbtb_view-models_jaxb_versioning[versioning]
@@ -79,10 +79,10 @@ It's quite common for view models to be "backed by" (be projections of) some und
 The `ToDoItemDto` we've been using as the example in this section is an example: there is an underlying `ToDoItem` entity.
 
 It wouldn't make sense to serialize out the state of a persistent entity: the point of a DTO is to act as a facade on top of the entity so that the implementation details (of the entity's structure) don't leak out to the consumer.
-However, the identity of the underlying entity can be well defined; Apache Isis defines the xref:rgcms.adoc#_rgcms_schema-common[Common schema] which defines the `<oid-dto>` element (and corresponding `OidDto` class): the object's type and its identifier.
-This is basically a formal XML equivalent to the `Bookmark` object obtained from the xref:rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`].
+However, the identity of the underlying entity can be well defined; Apache Isis defines the xref:../rgcms/rgcms.adoc#_rgcms_schema-common[Common schema] which defines the `<oid-dto>` element (and corresponding `OidDto` class): the object's type and its identifier.
+This is basically a formal XML equivalent to the `Bookmark` object obtained from the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`].
 
-There is only one requirement to make this work: every referenced domain entity must be annotated with xref:rgant.adoc#_rgant-XmlJavaTypeAdapter[`@XmlJavaTypeAdapter`], specifying the framework-provided `PersistentEntityAdapter.class`.
+There is only one requirement to make this work: every referenced domain entity must be annotated with xref:../rgant/rgant.adoc#_rgant-XmlJavaTypeAdapter[`@XmlJavaTypeAdapter`], specifying the framework-provided `PersistentEntityAdapter.class`.
 This class is similar to the `BookmarkService`: it knows how to create an `OidDto` from an object reference.
 
 Thus, in our view model we can legitimately write:
@@ -132,11 +132,11 @@ public class ToDoItemV1_1 implements Dto {
 
 
 There's nothing to prevent a JAXB DTO from containing rich graphs of data, parent containing children containing children.
-Be aware though that all of this state will become the DTO's memento, ultimately converted into a URL-safe form, by way of the xref:rgsvc.adoc#_rgsvc_spi_UrlEncodingService[`UrlEncodingService`].
+Be aware though that all of this state will become the DTO's memento, ultimately converted into a URL-safe form, by way of the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UrlEncodingService[`UrlEncodingService`].
 
 There are limits to the lengths of URLs, however.
 Therefore the DTO should not include state that can easily be derived from other information.
-If the URL does exceed limits, then provide a custom implementation of xref:rgsvc.adoc#_rgsvc_spi_UrlEncodingService[`UrlEncodingService`] to handle the memento string in some other fashion (eg substituting it with a GUID, with the memento cached somehow on the server).
+If the URL does exceed limits, then provide a custom implementation of xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UrlEncodingService[`UrlEncodingService`] to handle the memento string in some other fashion (eg substituting it with a GUID, with the memento cached somehow on the server).
 
 
 
@@ -256,7 +256,7 @@ There are therefore two options:
 * either choose not to have the view model DTO reference any persistent entities, and simply limit the DTO to simple scalars. +
 +
 Such a DTO will then be usable in both the Apache Isis app (to generate the original XML) and in the consumer.
-The xref:rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`] can be used to obtain the object identifiers
+The xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`] can be used to obtain the object identifiers
 
 * alternatively, generate a different DTO for the consumer from the XSD of the view model DTO.
 
@@ -296,7 +296,7 @@ In the todoapp this can be found in the `todoapp-xsd` Maven module, whose `pom.x
 </project>
 ----
 
-The `isis-xsd` profile generates the XSD using the xref:rgmvn.adoc#_rgmvn_xsd[`xsd` goal] of Isis' maven plugin:
+The `isis-xsd` profile generates the XSD using the xref:../rgmvn/rgmvn.adoc#_rgmvn_xsd[`xsd` goal] of Isis' maven plugin:
 
 [source,xml]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_programming-model.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_programming-model.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_programming-model.adoc
index 1a845f9..d4bb007 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_programming-model.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_programming-model.adoc
@@ -8,7 +8,7 @@
 
 So much for the theory; how should view models be implemented?  Fundamentally all view models' state is serialized into
 a string memento; this memento is then held by the client (browser) in the form of a URL.  As you might imagine, this
-URL can become quite long, but Apache Isis offers a mechanism (the xref:rgsvc.adoc#_rgsvc_spi_UrlEncodingService[`UrlEncodingService`]) if it exceeds the maximum length for a URL
+URL can become quite long, but Apache Isis offers a mechanism (the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UrlEncodingService[`UrlEncodingService`]) if it exceeds the maximum length for a URL
 (2083 characters).  Also, of course, this string memento must only contain characters that it is valid for use within
 a URL.
 
@@ -30,7 +30,7 @@ defining a view model so that the original intent is not lost.  They are:
 @DomainObject(nature=Nature.EXTERNAL_ENTITY)
 public class CustomerRecordOnSAP { ... }
 ----
-|Annotated with xref:rgant.adoc#_rgant-DomainObject_nature[`@DomainObject#nature()`] and a nature of `EXTERNAL_ENTITY`, with memento derived automatically from the properties of the domain object.  Collections are ignored, as are any properties annotated as xref:rgant.adoc#_rgant-Property_notPersisted[not persisted].
+|Annotated with xref:../rgant/rgant.adoc#_rgant-DomainObject_nature[`@DomainObject#nature()`] and a nature of `EXTERNAL_ENTITY`, with memento derived automatically from the properties of the domain object.  Collections are ignored, as are any properties annotated as xref:../rgant/rgant.adoc#_rgant-Property_notPersisted[not persisted].
 
 | In-memory entity
 |[source,java]
@@ -56,7 +56,7 @@ public class Dashboard { ... }
 public class Dashboard { ... }
 ----
 
-|Annotated with xref:rgant.adoc#_rgant-ViewModel[`@ViewModel`] annotation (effectively just an alias)' memento is as preceding: from "persisted" properties, collections ignored
+|Annotated with xref:../rgant/rgant.adoc#_rgant-ViewModel[`@ViewModel`] annotation (effectively just an alias)' memento is as preceding: from "persisted" properties, collections ignored
 
 |Application view model
 |
@@ -66,7 +66,7 @@ public class ExcelUploadManager implements ViewModel {
   public String viewModelMemento() { ... }
   public void viewModelInit(String memento) { ... }
 }
-|Implement xref:rgcms.adoc#_rgcms_classes_super_ViewModel[`ViewModel`] interface.  The memento is as defined by the
+|Implement xref:../rgcms/rgcms.adoc#_rgcms_classes_super_ViewModel[`ViewModel`] interface.  The memento is as defined by the
 interface's methods: the programmer has full control (but also full responsibility) for the string memento.
 
 |DTO
@@ -76,7 +76,7 @@ interface's methods: the programmer has full control (but also full responsibili
 @XmlRootElement("customer")
 public class CustomerDto { ... }
 ----
-|Annotate using JAXB xref:rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`] annotation.  Memento
+|Annotate using JAXB xref:../rgant/rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`] annotation.  Memento
 derived automatically by serializing the XML graph as implied by the JAXB annotations.  Note that (unlike `@ViewModel`
 et al) this state _can_ include collections.
 |===

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_use-cases.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_use-cases.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_use-cases.adoc
index 6667403..66c547e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_use-cases.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_use-cases.adoc
@@ -90,7 +90,7 @@ what the use cases are that those domain entities are trying to support.  You ce
 domain layer that could support every conceivable use case before starting to think about view models.
 
 Instead, you should iterate.  Identify the use case/story/end-user objective that you will deliver value to the
-business.  Then build out the minimum domain entities to support that use case (refining the xref:ugfun.adoc#__ugfun_core-concepts_philosophy_domain-driven-design_ubiquitous-language[ubiquitous language] as you
+business.  Then build out the minimum domain entities to support that use case (refining the xref:../ugfun/ugfun.adoc#__ugfun_core-concepts_philosophy_domain-driven-design_ubiquitous-language[ubiquitous language] as you
 go).  Then, identify if there any view models that could be introduced which would simplify the end-user interactions
 with the system (perhaps automating several related use cases together).
 ****
@@ -119,8 +119,8 @@ In case it's not obvious, these DTOs are still usable as "regular" view models;
 
 
 It's also worth noting that it is also possible to download the XML (or XSD) straight from the UI, useful during development.
-The view model simply needs to implement the xref:rgcms.adoc#_rgcms_classes_mixins_Dto[`Dto`] marker interface; the
-framework has xref:rgcms.adoc#_rgcms_classes_mixins_Dto[mixins] that contribute the download actions to the view model.
+The view model simply needs to implement the xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins_Dto[`Dto`] marker interface; the
+framework has xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins_Dto[mixins] that contribute the download actions to the view model.
 
 
 [[__ugbtb_view-models_use-cases_dtos_consumers]]
@@ -131,11 +131,11 @@ eg using the xref:ugvro.adoc#[RestfulObjects viewer], or may have the XML sent t
 such as Apache Camel.
 
 In the former case, the consumer requests the DTO by calling the REST API with the appropriate HTTP `Accept` header.
-An appropriate implementation of xref:rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`] can then be
+An appropriate implementation of xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`] can then be
 used to return the appropriate DTO (as XML).
 
 For the latter case, one design is simply for the application to instantiate the view model, then call the
-xref:rgsvc.adoc#_rgsvc_api_JaxbService[`JaxbService`] to obtain its corresponding XML.  This can then be published onto
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_JaxbService[`JaxbService`] to obtain its corresponding XML.  This can then be published onto
 the ESB, for example using an http://activemq.apache.org[Apache ActiveMQ (TM)] queue.
 
 However, rather than try to push all the data that might be needed by any of these external systems in a single XML event
@@ -149,8 +149,8 @@ This is an example of the link:https://leanpub.com/camel-design-patterns[VETRO p
 invoked), and the enrich (callback to obtain a DTO with additional information required by the consumer).
 ====
 
-The (non-ASF) http://github.com/isisaddons/isis-module-publishmq[Isis addons' publishmq] module provides an out-of-the-box solution of this design.  It provides an implementation of the xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`],
-but which simply publishes instances of xref:rgcms.adoc#_rgcms_schema-aim[`ActionInvocationMemento`] to an ActiveMQ
+The (non-ASF) http://github.com/isisaddons/isis-module-publishmq[Isis addons' publishmq] module provides an out-of-the-box solution of this design.  It provides an implementation of the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`],
+but which simply publishes instances of xref:../rgcms/rgcms.adoc#_rgcms_schema-aim[`ActionInvocationMemento`] to an ActiveMQ
 queue.  Camel (or similar) can then be hooked up to consume these events from this queue, and use a processor to
 parse the action memento to determine what has changed on the source system.  Thereafter, a subsequent Camel processor
 can then call back to the source - via the xref:ugvro.adoc[Restful Objects viewer] - to enrich the message with

[48/58] [abbrv] isis git commit: wip - ugfun.adoc - fixing bad includes etc

[da...@apache.org]

wip - ugfun.adoc - fixing bad includes etc


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/c1f4647f
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/c1f4647f
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/c1f4647f

Branch: refs/heads/wip
Commit: c1f4647f446fd3258f09888a186414b010159546
Parents: acf946c
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Tue Apr 18 00:28:23 2017 +0200
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Thu Apr 20 09:09:31 2017 +0100

----------------------------------------------------------------------
 .../ugfun/_ugfun_programming-model_domain-services_menu.adoc   | 4 ++--
 .../asciidoc/guides/ugfun/_ugfun_programming-model_mixins.adoc | 6 +++---
 2 files changed, 5 insertions(+), 5 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/c1f4647f/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_menu.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_menu.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_menu.adoc
index 64d3201..101a778 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_menu.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_menu.adoc
@@ -1,4 +1,4 @@
-[[_ugfun_programming-model_domain-services_menu]]
+    [[_ugfun_programming-model_domain-services_menu]]
 = Menu
 :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: ../../
@@ -62,7 +62,7 @@ public class CustomerMenu {
 <1> The (Apache Isis) xref:../rgant/rgant.adoc#_rgant_DomainService[`@DomainService`] annotation is used to identify the class as a domain service.
 Apache Isis scans the classpath looking for classes with this annotation, so there very little configuration other than to tell the framework which packages to scan underneath.
 The `VIEW_MENU_ONLY` nature indicates that this service's actions should be exposed as menu items.
-<3> The xref:../rgant/rgant.adoc#_rgant_DomainServiceLayout[`@DomainServiceLayout`] annotation provides UI hints.
+<2> The xref:../rgant/rgant.adoc#_rgant_DomainServiceLayout[`@DomainServiceLayout`] annotation provides UI hints.
 The menu is named "Customers" (otherwise it would have defaulted to "Customer Menu", based on the class name, while the xref:../rgant/rgant.adoc#_rgant_DomainServiceLayout_menuOrder[`menuOrder`] attribute determines the order of the menu with respect to other menu services.
 <3> The `findByName` method is annotated with various Apache Isis annotations (xref:../rgant/rgant.adoc#_rgant_Action[`@Action`], xref:../rgant/rgant.adoc#_rgant_ActionLayout[`@ActionLayout`] and xref:../rgant/rgant.adoc#_rgant_MemberOrder[`@MemberOrder`] and is itself rendered in the UI as a "Find By Name" menu item underneath the "Simple Objects" menu.
 <4> The xref:../rgant/rgant.adoc#_rgant_ParameterLayout[`@ParameterLayout`] provides metadata for the parameter itself, in this case its name.

http://git-wip-us.apache.org/repos/asf/isis/blob/c1f4647f/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_mixins.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_mixins.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_mixins.adoc
index d6c3f45..e585f5c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_mixins.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_mixins.adoc
@@ -48,10 +48,10 @@ include::_ugfun_programming-model_mixins_contributed-action.adoc[leveloffset=+1]
 
 include::_ugfun_programming-model_mixins_inferred-name.adoc[leveloffset=+1]
 
-include::_ugfun_programming-model_mixins_nested-static-classes  .adoc[leveloffset=+1]
+include::_ugfun_programming-model_mixins_nested-static-classes.adoc[leveloffset=+1]
 
-include::_ugfun_programming-model_mixins_programmatic-usage  .adoc[leveloffset=+1]
+include::_ugfun_programming-model_mixins_programmatic-usage.adoc[leveloffset=+1]
 
-include::_ugfun_programming-model_mixins_contributed-services  .adoc[leveloffset=+1]
+include::_ugfun_programming-model_mixins_contributed-services.adoc[leveloffset=+1]
 
 

[39/58] [abbrv] isis git commit: ISIS-1521: fixes some bad links between hints-n-tips

[da...@apache.org]

ISIS-1521: fixes some bad links between hints-n-tips


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/bef88147
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/bef88147
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/bef88147

Branch: refs/heads/wip
Commit: bef88147b7200271776fa7cf2f646f04cf8af84a
Parents: fcf368f
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Fri Apr 14 16:16:27 2017 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Thu Apr 20 09:09:30 2017 +0100

----------------------------------------------------------------------
 .../src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc          | 2 +-
 .../src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips.adoc    | 2 +-
 .../src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips.adoc    | 2 +-
 .../src/main/asciidoc/guides/ugsec/_ugsec_hints-and-tips.adoc    | 2 +-
 .../src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips.adoc    | 2 +-
 .../src/main/asciidoc/guides/ugvw/_ugvw_hints-and-tips.adoc      | 4 ++--
 6 files changed, 7 insertions(+), 7 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/bef88147/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc
index 26253ea..094550e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc
@@ -16,7 +16,7 @@ See also hints-n-tips chapters in the:
 
 * the xref:../ugvro/ugvro.adoc#_ugvro_hints-and-tips[Restful Objects viewer] guide
 
-* the xref:../ugvro/ugodn.adoc#_ugodn_hints-and-tips[Datanucleus ObjectStore] guide
+* the xref:../ugodn/ugodn.adoc#_ugodn_hints-and-tips[Datanucleus ObjectStore] guide
 
 * the xref:../ugsec/ugsec.adoc#_ugsec_hints-and-tips[Security] guide
 

http://git-wip-us.apache.org/repos/asf/isis/blob/bef88147/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips.adoc
index 589802f..2c78959 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips.adoc
@@ -16,7 +16,7 @@ See also hints-n-tips chapters in the:
 
 * the xref:../ugvro/ugvro.adoc#_ugvro_hints-and-tips[Restful Objects viewer] guide
 
-* the xref:../ugvro/ugodn.adoc#_ugodn_hints-and-tips[Datanucleus ObjectStore] guide
+* the xref:../ugodn/ugodn.adoc#_ugodn_hints-and-tips[Datanucleus ObjectStore] guide
 
 * the xref:../ugsec/ugsec.adoc#_ugsec_hints-and-tips[Security] guide
 

http://git-wip-us.apache.org/repos/asf/isis/blob/bef88147/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips.adoc
index 7bb687d..39ca25c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips.adoc
@@ -15,7 +15,7 @@ See also hints-n-tips chapters in the:
 
 * the xref:../ugvro/ugvro.adoc#_ugvro_hints-and-tips[Restful Objects viewer] guide
 
-* the xref:../ugvro/ugodn.adoc#_ugodn_hints-and-tips[Datanucleus ObjectStore] guide (this chapter)
+* the xref:../ugodn/ugodn.adoc#_ugodn_hints-and-tips[Datanucleus ObjectStore] guide (this chapter)
 
 * the xref:../ugsec/ugsec.adoc#_ugsec_hints-and-tips[Security] guide
 

http://git-wip-us.apache.org/repos/asf/isis/blob/bef88147/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_hints-and-tips.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_hints-and-tips.adoc b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_hints-and-tips.adoc
index 94eb956..97ccf36 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_hints-and-tips.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_hints-and-tips.adoc
@@ -17,7 +17,7 @@ See also hints-n-tips chapters in the:
 
 * the xref:../ugvro/ugvro.adoc#_ugvro_hints-and-tips[Restful Objects viewer] guide
 
-* the xref:../ugvro/ugodn.adoc#_ugodn_hints-and-tips[Datanucleus ObjectStore] guide
+* the xref:../ugodn/ugodn.adoc#_ugodn_hints-and-tips[Datanucleus ObjectStore] guide
 
 * the xref:../ugsec/ugsec.adoc#_ugsec_hints-and-tips[Security] guide (this chapter)
 

http://git-wip-us.apache.org/repos/asf/isis/blob/bef88147/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips.adoc
index a53db8a..fa9b85f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips.adoc
@@ -15,7 +15,7 @@ See also hints-n-tips chapters in the:
 
 * the xref:../ugvro/ugvro.adoc#_ugvro_hints-and-tips[Restful Objects viewer] guide (this chapter)
 
-* the xref:../ugvro/ugodn.adoc#_ugodn_hints-and-tips[Datanucleus ObjectStore] guide
+* the xref:../ugodn/ugodn.adoc#_ugodn_hints-and-tips[Datanucleus ObjectStore] guide
 
 * the xref:../ugsec/ugsec.adoc#_ugsec_hints-and-tips[Security] guide
 

http://git-wip-us.apache.org/repos/asf/isis/blob/bef88147/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_hints-and-tips.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_hints-and-tips.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_hints-and-tips.adoc
index c736afb..8b7282b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_hints-and-tips.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_hints-and-tips.adoc
@@ -1,4 +1,4 @@
-[[_ugvro_hints-and-tips]]
+[[_ugvw_hints-and-tips]]
 = Hints and Tips
 :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: ../../
@@ -16,7 +16,7 @@ See also hints-n-tips chapters in the:
 
 * the xref:../ugvro/ugvro.adoc#_ugvro_hints-and-tips[Restful Objects viewer] guide
 
-* the xref:../ugvro/ugodn.adoc#_ugodn_hints-and-tips[Datanucleus ObjectStore] guide
+* the xref:../ugodn/ugodn.adoc#_ugodn_hints-and-tips[Datanucleus ObjectStore] guide
 
 * the xref:../ugsec/ugsec.adoc#_ugsec_hints-and-tips[Security] guide
 

[25/58] [abbrv] isis git commit: ISIS-1521: working on ugfun.adoc

[da...@apache.org]

ISIS-1521: working on ugfun.adoc


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/2f2714cc
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/2f2714cc
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/2f2714cc

Branch: refs/heads/wip
Commit: 2f2714cc32230f4304256c07bdd48f99c8b63ab0
Parents: 31534e5
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Mon Apr 17 11:31:17 2017 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Thu Apr 20 09:09:30 2017 +0100

----------------------------------------------------------------------
 .../src/main/asciidoc/downloads.adoc            |   3 +-
 .../guides/rgcms/_rgcms_schema-common.adoc      |   2 +-
 .../ugbtb/_ugbtb_decoupling_contributions.adoc  |  81 +--
 .../guides/ugbtb/_ugbtb_decoupling_mixins.adoc  | 269 --------
 .../guides/ugbtb/_ugbtb_view-models.adoc        |  18 -
 .../guides/ugbtb/_ugbtb_view-models_jaxb.adoc   | 415 ------------
 .../_ugbtb_view-models_programming-model.adoc   |  89 ---
 .../src/main/asciidoc/guides/ugbtb/ugbtb.adoc   |   1 -
 .../ugfun/_ugfun_available-domain-services.adoc |  18 +
 ...able-domain-services_framework-provided.adoc | 107 ++++
 ...vailable-domain-services_incode-catalog.adoc |  31 +
 ...n_available-domain-services_isis-addons.adoc |  41 ++
 .../guides/ugfun/_ugfun_building-blocks.adoc    |  23 +
 .../ugfun/_ugfun_building-blocks_events.adoc    |  79 +++
 .../_ugfun_building-blocks_identifiers.adoc     |  14 +
 .../_ugfun_building-blocks_identifiers_oid.adoc |  47 ++
 ...lding-blocks_identifiers_title-and-icon.adoc |  27 +
 .../ugfun/_ugfun_building-blocks_metamodel.adoc |  32 +
 .../ugfun/_ugfun_building-blocks_modules.adoc   |  15 +
 .../_ugfun_building-blocks_object-members.adoc  |  87 +++
 ...building-blocks_types-of-domain-objects.adoc |  35 +
 ...types-of-domain-objects_domain-entities.adoc |  37 ++
 ...types-of-domain-objects_domain-services.adoc |  66 ++
 ...g-blocks_types-of-domain-objects_mixins.adoc |  56 ++
 ...cks_types-of-domain-objects_view-models.adoc | 162 +++++
 .../guides/ugfun/_ugfun_class-structure.adoc    |  46 --
 .../ugfun/_ugfun_class-structure_actions.adoc   | 264 --------
 .../_ugfun_class-structure_collections.adoc     | 121 ----
 .../_ugfun_class-structure_domain-services.adoc | 155 -----
 .../_ugfun_class-structure_inject-services.adoc | 103 ---
 ...lass-structure_properties-vs-parameters.adoc |  38 --
 .../_ugfun_class-structure_properties.adoc      | 369 -----------
 .../guides/ugfun/_ugfun_core-concepts.adoc      |   6 +-
 .../ugfun/_ugfun_core-concepts_add-ons.adoc     |  54 --
 .../_ugfun_core-concepts_apache-isis-vs.adoc    |   2 +-
 ...ache-isis-vs_mvc-server-side-frameworks.adoc |  29 -
 ...concepts_apache-isis-vs_mvc-server-side.adoc |  29 +
 .../_ugfun_core-concepts_building-blocks.adoc   | 314 ---------
 ..._ugfun_core-concepts_deployment-options.adoc |  93 +++
 ...re-concepts_framework-provided-services.adoc | 107 ----
 ..._core-concepts_other-deployment-options.adoc |  81 ---
 .../ugfun/_ugfun_domain-class-ontology.adoc     |  45 --
 ...n_domain-class-ontology_domain-entities.adoc |  86 ---
 ...n_domain-class-ontology_domain-services.adoc | 229 -------
 .../_ugfun_domain-class-ontology_mixins.adoc    |  56 --
 ...ugfun_domain-class-ontology_view-models.adoc | 196 ------
 .../guides/ugfun/_ugfun_programming-model.adoc  |  91 +++
 .../ugfun/_ugfun_programming-model_actions.adoc | 264 ++++++++
 .../_ugfun_programming-model_collections.adoc   | 121 ++++
 ...ugfun_programming-model_domain-entities.adoc |  89 +++
 ...ugfun_programming-model_domain-services.adoc | 383 +++++++++++
 ...ugfun_programming-model_inject-services.adoc | 103 +++
 .../ugfun/_ugfun_programming-model_mixins.adoc  | 346 ++++++++++
 ...gramming-model_properties-vs-parameters.adoc |  38 ++
 .../_ugfun_programming-model_properties.adoc    | 369 +++++++++++
 .../_ugfun_programming-model_view-models.adoc   | 631 +++++++++++++++++++
 .../building-blocks/types-of-domain-object.png  | Bin 30851 -> 0 bytes
 .../building-blocks/types-of-domain-object.pptx | Bin 64342 -> 0 bytes
 .../hexagonal-architecture-addons.png           | Bin 128533 -> 0 bytes
 .../action-semantics-are-you-sure.png           | Bin 11046 -> 0 bytes
 .../tips-n-tricks/are-you-sure-happy-case.png   | Bin 9993 -> 0 bytes
 .../tips-n-tricks/are-you-sure-sad-case.png     | Bin 10515 -> 0 bytes
 .../how-tos/tips-n-tricks/are-you-sure.png      | Bin 9312 -> 0 bytes
 .../src/main/asciidoc/guides/ugfun/ugfun.adoc   |   9 +-
 .../guides/ugodn/_ugodn_hints-and-tips.adoc     |   1 +
 ..._ugodn_hints-and-tips_mapping-to-a-view.adoc |   9 +
 .../_ugvro_simplified-representations.adoc      | 366 +----------
 ...ified-representations_action-invocation.adoc | 128 ++++
 ...ied-representations_apache-isis-profile.adoc |  38 ++
 ...epresentations_configuration-properties.adoc |   2 +-
 ...implified-representations_domain-object.adoc |  92 +++
 ...ified-representations_object-collection.adoc |  82 +++
 ...d-representations_other-representations.adoc |  37 ++
 .../tg/_tg_stop-scaffolding-start-coding.adoc   |   8 +-
 74 files changed, 3848 insertions(+), 3537 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/downloads.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/downloads.adoc b/adocs/documentation/src/main/asciidoc/downloads.adoc
index 3ecfa73..65456b0 100644
--- a/adocs/documentation/src/main/asciidoc/downloads.adoc
+++ b/adocs/documentation/src/main/asciidoc/downloads.adoc
@@ -7,7 +7,8 @@
 
 
 Apache Isis&trade; software is a framework for rapidly developing domain-driven apps in Java.
-Write your business logic in entities, domain services and repositories, and the framework dynamically generates a representation of that domain model as a webapp or RESTful API. Use for prototyping or production.
+Write your business logic in entities, domain services and repositories, and the framework dynamically generates a representation of that domain model as a webapp or RESTful API.
+Use for prototyping or production.
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-common.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-common.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-common.adoc
index d3411a1..20e2a30 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-common.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-common.adoc
@@ -16,7 +16,7 @@ the `Bookmark` object obtained from the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_Book
 
 Although simple, this is an enormously powerful concept, in that it represents a URI to any domain object managed by
 a given Apache Isis application.  With it, we have the ability to lookup any arbitrary object.  Further discussion and
-examples can be found xref:../ugfun/ugfun.adoc#__ugfun_core-concepts_building-blocks_oid[here].
+examples can be found xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_identifiers_oid[here].
 
 The `oidDto` complex type is defined as:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_contributions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_contributions.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_contributions.adoc
index 6e93ac7..09844ad 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_contributions.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_contributions.adoc
@@ -5,83 +5,4 @@
 :_imagesdir: images/
 
 
-Contributed services provide many of the same benefits as xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_mixins[mixins];
-indeed mixins are an evolution and refinement of the contributions concept.
-
-[WARNING]
-====
-It's possible that contributions may be deprecated and eventually removed in a future version of the framework, to be replaced entirely by mixins.
-====
-
-The main difference between contributed services and mixins is that the actions of a contributed service will
-contribute to _all_ the parameters of its actions, whereas a mixin only contributes to the type accepted in its
-constructor.  Also, contributed services are long-lived
-singletons, whereas mixins are instantiated as required (by the framework) and then discarded almost immediately.
-
-[NOTE]
-====
-There's further useful information on contributed services in the reference guide, discussing the xref:../rgant/rgant.adoc#_rgant-DomainService_nature[@DomainService#nature()] attribute, for the `NatureOfService.VIEW_CONTRIBUTIONS_ONLY` nature.
-====
-
-
-== Syntax
-
-Any n-parameter action provided by a service will automatically be contributed to the list of actions for each of its (entity) parameters. From the viewpoint of the entity the action is called a contributed action.
-
-For example, given a service:
-
-[source,java]
-----
-public interface Library {
-    public Loan borrow(Loanable l, Borrower b);
-}
-----
-
-and the entities:
-
-[source,java]
-----
-public class Book implements Loanable { ... }
-----
-
-and
-
-[source,java]
-----
-public class LibraryMember implements Borrower { ... }
-----
-
-then the `borrow(...)` action will be contributed to both `Book` and to `LibraryMember`.
-
-This is an important capability because it helps to decouple the concrete classes from the services.
-
-If necessary, though, this behaviour can be suppressed by annotating the service action with `@org.apache.isis.applib.annotations.NotContributed`.
-
-For example:
-
-[source,java]
-----
-public interface Library {
-    @NotContributed
-    public Loan borrow(Loanable l, Borrower b);
-}
-----
-
-If annotated at the interface level, then the annotation will be inherited by every concrete class. Alternatively the annotation can be applied at the implementation class level and only apply to that particular implementation.
-
-Note that an action annotated as being `@NotContributed` will still appear in the service menu for the service. If an action should neither be contributed nor appear in service menu items, then simply annotate it as `@Hidden`.
-
-
-## Contributed Action
-
-NOTE: FIXME
-
-## Contributed Property
-
-NOTE: FIXME
-
-## Contributed Collection
-
-NOTE: FIXME
-
-
+NOTE: FIXME - combine with mixins, above
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_mixins.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_mixins.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_mixins.adoc
index 72af4c3..566b840 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_mixins.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_mixins.adoc
@@ -5,273 +5,4 @@
 :_imagesdir: images/
 
 
-A mixin object allows one class to contribute behaviour - actions, (derived) properties and (derived) collections - to another domain object, either a domain entity or view model.
-
-Some programming languages use the term "trait" instead of mixin, and some languages (such as AspectJ) define their own syntax for defining such constructs.
-In Apache Isis a mixin is very similar to a domain service, however it also defines a single 1-arg constructor that defines the type of the domain objects that it contributes to.
-
-Why do this?
-Two reasons:
-
-* The main reason is to allow the app to be decoupled, so that it doesn't degrade into the proverbial link:http://www.laputan.org/mud/mud.html#BigBallOfMud["big ball of mud"].
-Mixins (and contributions) allow dependency to be inverted, so that the dependencies between modules can be kept acyclic and under control.
-
-* However, there is another reason: mixins are also a convenient mechanism for grouping functionality even for a concrete type, helping to rationalize about the dependency between the data and the behaviour.
-
-Both use cases are discussed below.
-
-Syntactically, a mixin is defined using either the xref:../rgant/rgant.adoc#_rgant_Mixin[`@Mixin`] annotation or using xref:../rgant/rgant.adoc#_rgant_DomainObject_nature[`@DomainObject#nature()`] attribute (specifying a nature of `Nature.MIXIN`).
-
-
-== Contributed Collection
-
-The example below shows how to contribute a collection:
-
-[source,java]
-----
-@Mixin
-public class DocumentHolderDocuments {
-
-    private final DocumentHolder holder;
-    public DocumentHolderDocuments(DocumentHolder holder) { this.holder = holder; }
-
-    @Action(semantics=SemanticsOf.SAFE)                         // <1>
-    @ActionLayout(contributed = Contributed.AS_ASSOCIATION)     // <2>
-    @CollectionLayout(render = RenderType.EAGERLY)
-    public List<Document> documents() {                         // <3>
-        ...
-    }
-    public boolean hideDocuments() { ... }                      // <4>
-}
-----
-<1> required; actions that have side-effects cannot be contributed as collections
-<2> required; otherwise the mixin will default to being rendered as an action
-<3> must accept no arguments.
-    The mixin is a collection rather than a property because the return type is a collection, not a scalar.
-<4> supporting methods follow the usual naming conventions.
-    (That said, in the case of collections, because the collection is derived/read-only, the only supporting method that is relevant is `hideXxx()`).
-
-The above will result in a contributed collection for all types that implement/extend from `DocumentHolder` (so is probably for a mixin across modules).
-
-
-
-== Contributed Property
-
-Contributed properties are defined similarly, for example:
-
-[source,java]
-----
-@Mixin
-public class DocumentHolderMostRecentDocument {
-
-    private final DocumentHolder holder;
-    public DocumentHolderDocuments(DocumentHolder holder) { this.holder = holder; }
-
-    @Action(semantics=SemanticsOf.SAFE)                         // <1>
-    @ActionLayout(contributed = Contributed.AS_ASSOCIATION)     // <2>
-    public Document> mostRecentDocument() {                     // <3>
-        ...
-    }
-    public boolean hideMostRecentDocument() { ... }             // <4>
-}
-----
-<1> required; actions that have side-effects cannot be contributed as collections
-<2> required; otherwise the mixin will default to being rendered as an action
-<3> must accept no arguments.
-    The mixin is a property rather than a collection because the return type is a scalar.
-<4> supporting methods follow the usual naming conventions.
-    (That said, in the case of properties, because the property is derived/read-only, the only supporting method that is relevant is `hideXxx()`).
-
-
-== Contributed Action
-
-Contributed properties are defined similarly, for example:
-
-[source,java]
-----
-@Mixin
-public class DocumentHolderAddDocument {
-
-    private final DocumentHolder holder;
-    public DocumentHolderDocuments(DocumentHolder holder) { this.holder = holder; }
-
-    @Action()
-    @ActionLayout(contributed = Contributed.AS_ACTION)          // <1>
-    public Document> addDocument(Document doc) {
-        ...
-    }
-    public boolean hideAddDocument() { ... }                    // <2>
-}
-----
-<1> recommended
-<2> supporting methods follow the usual naming conventions.
-
-
-== Inferred Name
-
-Where the mixin follows the naming convention `SomeType_mixinName` then the method name can be abbreviated to "$$".
-The mixin name is everything after the last '_'.
-
-For example:
-
-[source,java]
-----
-@Mixin
-public class DocumentHolder_documents {
-
-    private final DocumentHolder holder;
-    public DocumentHolder_documents(DocumentHolder holder) { this.holder = holder; }
-
-    @Action(semantics=SemanticsOf.SAFE)
-    @ActionLayout(contributed = Contributed.AS_ASSOCIATION)
-    @CollectionLayout(render = RenderType.EAGERLY)
-    public List<Document> $$() {                                    // <1>
-        ...
-    }
-    public boolean hide$$() { ... }                                 // <2>
-}
-----
-<1> using "$$" as the reserved method name
-<2> supporting methods as usual
-
-The character "$" is also recognized as a separator between the mixin type and mixin name.
-This is useful for mixins implemented as nested static types, discussed below.
-
-
-== As Nested Static Classes
-
-As noted in the introduction, while mixins were originally introduced as a means of allowing contributions from one module to the types of another module, they are also a convenient mechanism for grouping functionality/behaviour against a concrete type.
-All the methods and supporting methods end up in a single construct, and the dependency between that functionality and the rest of the object is made more explicit.
-
-When using mixins in this fashion, it is idiomatic to write the mixin as a nested static class, using the naming convention described above to reduce duplication.
-
-For example:
-
-[source,java]
-----
-public class Customer {
-
-    @Mixin
-    public static class placeOrder {                                            // <1>
-
-        private final Customer customer;
-        public documents(Customer customer) { this.customer = customer; }       // <2>
-
-        @Action
-        @ActionLayout(contributed = Contributed.AS_ACTION)
-        public List<Order> $$(Product p, int quantity) {                        // <3>
-            ...
-        }
-        public boolean hide$$() { ... }                                         // <4>
-        public String validate0$$(Product p) { ...  }
-    }
-}
-----
-<1> Prior to `1.13.2`, had to be prefixed by an "_"; this is no longer required because "$" is also recognized as a way of parsing the class name in order to infer the mixin's name (eg `Customer$placeOrder`).
-<2> typically contributed to concrete class
-<3> using the "$$" reserved name
-<4> supporting methods as usual
-
-
-Moreover, the mixin class can be capitalized if desired.
-Thus:
-
-[source,java]
-----
-public class Customer {
-
-    @Mixin
-    public static class PlaceOrder {                                            // <1>
-
-        private final Customer customer;
-        public documents(Customer customer) { this.customer = customer; }       // <2>
-
-        @Action
-        @ActionLayout(contributed = Contributed.AS_ACTION)
-        public List<Order> $$(Product p, int quantity) {                        // <3>
-            ...
-        }
-        public boolean hide$$() { ... }                                         // <4>
-        public String validate0$$(Product p) { ...  }
-    }
-}
-----
-
-
-In other words, all of the following are allowed:
-
-* `public static class Documents { ... }`
-* `public static class documents { ... }`
-* `public static class _Documents { ... }`
-* `public static class _documents { ... }`
-
-The reserved method name "$$" can also be changed using xref:../rgant/rgant.adoc#_rgant_Mixin_method[`@Mixin#method()`] or xref:../rgant/rgant.adoc#_rgant_DomainObject_mixinMethod[`@DomainObject#mixinMethod()`].
-
-
-
-
-
-
-
-
-== Programmatic usage
-
-When a domain object is rendered, the framework will automatically instantiate all required mixins and delegate to them
-dynamically.  If writing integration tests or fixtures, or (sometimes) just regular domain logic, then you may need to
-instantiate mixins directly.
-
-For this you can use the
-xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-creation-api[`DomainObjectContainer#mixin(...)`
-method.  For example:
-
-[source,java]
-----
-DocumentHolder_documents mixin = container.mixin(DocumentHolder_documents.class, customer);
-----
-
-The xref:../ugtst/ugtst.adoc#__ugtst_integ-test-support_bootstrapping_IntegrationTestAbstract[`IntegrationTestAbstract`] and
-xref:../rgcms/rgcms.adoc#_rgcms_classes_super_FixtureScript[`FixtureScript`] classes both provide a `mixin(...)` convenience
-method.
-
-
-
-== Other reasons to use mixins
-
-In the introduction to this topic we mentioned that mixins are most useful for ensuring that the domain app remains
-decoupled.  This applies to the case where the contributee (eg `Customer`, being mixed into) is in one module, while
-the contributor mixin (`DocumentHolder_documents`) is in some other module.  The `customer` module knows about the
-`document` module, but not vice versa.
-
-However, you might also want to consider moving behaviour out of entities even within the same module, perhaps even
-within the same Java package.  And the reason for this is to support hot-reloading of Java classes, so that you can
-modify and recompile your application without having to restart it.  This can provide substantial productivity gains.
-
-The Hotspot JVM has limited support for hot reloading; generally you can change method implementations but you cannot
-introduce new methods.  However, the link:https://dcevm.github.io/[DCEVM] open source project will patch the JVM to
-support much more complete hot reloading support.  There are also, of course, commercial products such as JRebel.
-
-The main snag in all this is the DataNucleus enhancer... any change to entities is going to require the entity to be
-re-enhanced, and the JDO metamodel recreated, which usually "stuffs things up".  So hot-reloading of an app whose
-fundamental structure is changing is likely to remain a no-no.
-
-However, chances are that the structure of your domain objects (the data) will change much less rapidly than
-the behaviour of those domain objects.  Thus, it's the behaviour that you're most likely wanting to change while the
-app is still running.  If you move that behaviour out into xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins[mixins] (or
-xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_contributions[contributed services]), then these can be reloaded happily.
-(When running in prototype mode), Apache Isis will automatically recreate the portion of the metamodel for any domain
-object as it is rendered.
-
-
-
-== Related reading
-
-Mixins are an implementation of the link:http://www.artima.com/articles/dci_vision.html[DCI architecture] architecture, as formulated and described by link:https://en.wikipedia.org/wiki/Trygve_Reenskaug[Trygve Reenskaug] and link:https://en.wikipedia.org/wiki/Jim_Coplien[Jim Coplien].  Reenskaug was the inventor of the MVC pattern (and also the external
-examiner for Richard Pawson's PhD thesis), while Coplien has a long history in object-orientation, C++ and patterns.
-
-DCI stands for Data-Context-Interaction and is presented as an evolution of object-oriented programming, but one where
-behaviour is bound to objects dynamically rather than statically in some context or other.  The `@Mixin`
-pattern is Apache Isis' straightforward take on the same basic concept.
-
-You might also wish to check out link:http://zest.apache.org[Apache Zest] (formerly Qi4J), which implements a much more
-general purpose implementation of the same concepts.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models.adoc
deleted file mode 100644
index 0efd664..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models.adoc
+++ /dev/null
@@ -1,18 +0,0 @@
-[[_ugbtb_view-models]]
-= View Models
-: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/
-
-
-View models are a type of domain object (with state, behaviour etc) but where the state is _not_ persisted into the
- JDO/DataNucleus-managed database, but is instead converted to/from a string memento, and held by the calling client.
-This opens up a number of more advanced use cases.
-
-In this topic we'll explore those use cases, and learn the programming model and conventions to use view models in your application.
-
-
-include::_ugbtb_view-models_programming-model.adoc[leveloffset=+1]
-include::_ugbtb_view-models_jaxb.adoc[leveloffset=+1]
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_jaxb.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_jaxb.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_jaxb.adoc
deleted file mode 100644
index fe49916..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_jaxb.adoc
+++ /dev/null
@@ -1,415 +0,0 @@
-[[_ugbtb_view-models_jaxb]]
-= JAXB-annotated View Models/DTOs
-: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/
-
-
-
-As noted in the xref:../ugfun/ugfun.adoc#_ugfun_domain-class-ontology_view-models[introduction], view models can also be defined using JAXB annotations.
-The serialized form of these view models is therefore XML, which also enables these view models
-to act as DTOs.
-
-In case it's not obvious, these DTOs are still usable as "regular" view models; they will render in the xref:../ugvw/ugvw.adoc#[Wicket viewer] just like any other.
-In fact, these JAXB-annotated view models are in many regards the most powerful of all the various ways of writing view models:
-
-* their entire state (collections as well as properties) is automatically managed from interaction to interaction. +
-+
-In contrast, using xref:../rgant/rgant.adoc#_rgant-ViewModel[`@ViewModel`] (or its xref:../rgant/rgant.adoc#_rgant-DomainObject_nature[`@DomainObject#nature()`] equivalent) will only manage the state of properties, but not collections.
-And if using the xref:../rgcms/rgcms.adoc#_rgcms_classes_super_ViewModel[`ViewModel`] interface, then the programmer must write all the state management (lots of boilerplate).
-
-* JAXB-annotated view models are "in effect" editable.
-
-The examples in this section uses the DTO for `ToDoItem`, taken from the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp].
-This DTO is defined as follows:
-
-[source,java]
-----
-package todoapp.app.viewmodels.todoitem.v1;                         // <1>
-@XmlRootElement(name = "toDoItemDto")                               // <2>
-@XmlType(
-        propOrder = {                                               // <3>
-            "majorVersion", "minorVersion",
-            "description", "category", ...
-            "toDoItem", "similarItems"
-        }
-)
-@DomainObjectLayout(
-        titleUiEvent = TitleUiEvent.Doop.class                      // <4>
-)
-public class ToDoItemV1_1 implements Dto {                          // <5>
-    @XmlElement(required = true, defaultValue = "1")                // <6>
-    public final String getMajorVersion() { return "1"; }
-    @XmlElement(required = true, defaultValue = "1")                // <7>
-    public String getMinorVersion() { return "1"; }
-
-    @XmlElement(required = true)                                    // <8>
-    @Getter @Setter
-    protected String description;
-    @XmlElement(required = true)
-    @Getter @Setter
-    protected String category;
-    ...
-
-    @Getter @Setter                                                 // <9>
-    protected ToDoItem toDoItem;
-    @XmlElementWrapper                                              // <10>
-    @XmlElement(name = "todoItem")
-    @Getter @Setter
-    protected List<ToDoItem> similarItems = Lists.newArrayList();
-}
-----
-<1> package name encodes major version; see discussion on xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_versioning[versioning]
-<2> identifies this class as a view model and defines the root element for JAXB serialization
-<3> all properties in the class must be listed; (they can be ignored using `@XmlTransient`)
-<4> demonstrating use of UI events for a subscriber to provide the DTO's title; see xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_titleUiEvent[`@DomainObjectLayout#titleUiEvent()`].
-<5> class name encodes (major and) minor version; see discussion on xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_versioning[versioning]
-<6> again, see discussion on xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_versioning[versioning]
-<7> again, see discussion on xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_versioning[versioning]
-<8> simple scalar properties
-<9> reference to a persistent entity; discussed xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_referencing-domain-entities[below]
-<10> reference to a collection of persistent entities; again discussed xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_referencing-domain-entities[below]
-
-
-
-[[__ugbtb_view-models_jaxb_referencing-domain-entities]]
-== Referencing Domain Entities
-
-It's quite common for view models to be "backed by" (be projections of) some underlying domain entity.
-The `ToDoItemDto` we've been using as the example in this section is an example: there is an underlying `ToDoItem` entity.
-
-It wouldn't make sense to serialize out the state of a persistent entity: the point of a DTO is to act as a facade on top of the entity so that the implementation details (of the entity's structure) don't leak out to the consumer.
-However, the identity of the underlying entity can be well defined; Apache Isis defines the xref:../rgcms/rgcms.adoc#_rgcms_schema-common[Common schema] which defines the `<oid-dto>` element (and corresponding `OidDto` class): the object's type and its identifier.
-This is basically a formal XML equivalent to the `Bookmark` object obtained from the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`].
-
-There is only one requirement to make this work: every referenced domain entity must be annotated with xref:../rgant/rgant.adoc#_rgant-XmlJavaTypeAdapter[`@XmlJavaTypeAdapter`], specifying the framework-provided `PersistentEntityAdapter.class`.
-This class is similar to the `BookmarkService`: it knows how to create an `OidDto` from an object reference.
-
-Thus, in our view model we can legitimately write:
-
-[source,java]
-----
-package todoapp.app.viewmodels.todoitem.v1;
-...
-public class ToDoItemV1_1 implements Dto {
-    ...
-    @Getter @Setter
-    protected ToDoItem toDoItem;
-}
-----
-
-All we need to do is remember to add that `@XmlJavaTypeAdapter` annotation to the referenced entity:
-
-[source,java]
-----
-@XmlJavaTypeAdapter(PersistentEntityAdapter.class)
-public class ToDoItem ...  {
-    ...
-}
-----
-
-
-It's also possible for a DTO to hold collections of objects.
-These can be of any type, either simple properties, or references to other objects.
-The only bit of boilerplate that is required is the `@XmlElementWrapper` annotation.
-This instructs JAXB to create an XML element (based on the field name) to contain each of the elements.
-(If this is omitted then the contents of the collection are at the same level as the properties; almost certainly not what is required).
-
-For example, the DTO also contains:
-
-[source,java]
-----
-package todoapp.app.viewmodels.todoitem.v1;
-...
-public class ToDoItemV1_1 implements Dto {
-    ...
-    @XmlElementWrapper
-    @XmlElement(name = "todoItem")
-    @Getter @Setter
-    protected List<ToDoItem> similarItems = Lists.newArrayList();
-}
-----
-
-
-There's nothing to prevent a JAXB DTO from containing rich graphs of data, parent containing children containing children.
-Be aware though that all of this state will become the DTO's memento, ultimately converted into a URL-safe form, by way of the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UrlEncodingService[`UrlEncodingService`].
-
-There are limits to the lengths of URLs, however.
-Therefore the DTO should not include state that can easily be derived from other information.
-If the URL does exceed limits, then provide a custom implementation of xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UrlEncodingService[`UrlEncodingService`] to handle the memento string in some other fashion (eg substituting it with a GUID, with the memento cached somehow on the server).
-
-
-
-
-
-[[__ugbtb_view-models_jaxb_versioning]]
-== Versioning
-
-The whole point of using DTOs (in Apache Isis, at least) is to define a formal contact between two inter-operating but independent applications.
-Since the only thing we can predicate about the future with any certainty is that it one or both of these applications will change, we should version DTOs from the get-go.
-This allows us to make changes going forward without unnecessarily breaking existing consumers of the data.
-
-[NOTE]
-====
-There are several ways that versioning might be accomplished; we base our guidelines on this link:http://www.xfront.com/Versioning.pdf[article] taken from Roger Costello's blog, well worth a read.
-====
-
-We can distinguish two types of changes:
-
-* backwardly compatible changes
-* breaking changes.
-
-We can immediately say that the XSD namespace should change only when there is a major/breaking change, if following link:http://semver.org[semantic versioning] that means when we bump the major version number v1, v2, etc.
-
-XML namespaces correspond (when using JAXB) to Java packages.
-We should therefore place our DTOs in a package that contains only the major number; this package will eventually contain a range of DTOs that are intended to be backwardly compatible with one another.
-The package should also have a `package-info.java`; it is this that declares the XSD namespace:
-
-[source,java]
-----
-@javax.xml.bind.annotation.XmlSchema(
-        namespace = "http://viewmodels.app.todoapp/todoitem/v1/Dto.xsd",        // <1>
-        xmlns = {
-                @javax.xml.bind.annotation.XmlNs(
-                        namespaceURI = "http://isis.apache.org/schema/common",
-                        prefix = "com"
-                )
-        },
-        elementFormDefault = javax.xml.bind.annotation.XmlNsForm.QUALIFIED
-)
-package todoapp.app.viewmodels.todoitem.v1;                                     // <2>
-----
-<1> the namespace URI, used by the DTO residing in this package.
-<2> the package in which the DTO resides.  Note that this contains only the major version.
-
-Although there is no requirement for the namespace URI to correspond to a physical URL, it should be unique.
-This usually means including a company domain name within the string.
-
-As noted above, this package will contain multiple DTO classes all with the same namespace; these represent a set of minor versions of the DTO, each subsequent one intended to be backwardly compatible with the previous.
-Since these DTO classes will all be in the same package (as per the xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_using-packages-to-version[advice above]), the class should therefore include the minor version name:
-
-[source,java]
-----
-package todoapp.app.viewmodels.todoitem.v1;     // <1>
-...
-public class ToDoItemV1_1 implements Dto {      // <2>
-    ...
-}
-----
-<1> package contains the major version only
-<2> DTO class contains the (major and) minor version
-
-
-We also recommend that each DTO instance should also specify the version of the XSD schema that it is logically compatible with.
-Probably most consumers will not persist the DTOs; they will be processed and then discarded.
-However, it would be wrong to assume that is the case in all cases; some consumers might choose to persist the DTO (eg for replay at some later state).
-
-Thus:
-
-[source,java]
-----
-public class ToDoItemV1_1 implements Dto {
-    @XmlElement(required = true, defaultValue = "1")
-    public final String getMajorVersion() { return "1"; }   // <1>
-    @XmlElement(required = true, defaultValue = "1")
-    public String getMinorVersion() { return "1"; }         // <2>
-    ...
-}
-----
-<1> returns the major version (in sync with the package)
-<2> returns the minor version (in sync with the class name)
-
-These methods always return a hard-coded literal.
-Any instances serialized from these classes will implicitly "declare" the (major and) minor version of the schema with which they are compatible.
-If a consumer has a minimum version that it requires, it can therefore inspect the XML instance itself to determine if it is able to consume said XML.
-
-If a new (minor) version of a DTO is required, then we recommend copying-and-pasting the previous version, eg:
-
-[source,java]
-----
-public class ToDoItemV1_2 implements Dto {
-    @XmlElement(required = true, defaultValue = "1")
-    public final String getMajorVersion() { return "1"; }
-    @XmlElement(required = true, defaultValue = "2")
-    public String getMinorVersion() { return "2"; }
-    ...
-}
-----
-
-Obviously, only changes made must be backward compatible, eg new members must be optional.
-
-Alternatively, you might also consider simply editing the source file, ie renaming the class and bumping up the value returned by `getMinorVersion()`.
-
-We also _don't_ recommend using inheritance (ie `ToDoItemV1_2` should not inherit from `ToDoItemV1_1`; this creates unnecessary complexity downstream if generating XSDs and DTOs for the downstream consumer.
-
-
-[[__ugbtb_view-models_jaxb_generating-xsds-and-dtos]]
-== Generating XSDs and DTOs
-
-In the section xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_referencing-domain-entities[above] it was explained how a view model DTO can transparent reference any "backing" entities; these references are converted to internal object identifiers.
-
-However, if the consumer of the XML is another Java process (eg running within an Apache Camel route), then you might be tempted/expect to be able to use the same DTO within that Java process.
-After a little thought though you'll realize that (duh!) of course you cannot; the consumer runs in a different process space, and will not have references to those containing entities.
-
-There are therefore two options:
-
-* either choose not to have the view model DTO reference any persistent entities, and simply limit the DTO to simple scalars. +
-+
-Such a DTO will then be usable in both the Apache Isis app (to generate the original XML) and in the consumer.
-The xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`] can be used to obtain the object identifiers
-
-* alternatively, generate a different DTO for the consumer from the XSD of the view model DTO.
-
-The (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] uses the second approach; generating the XSD and consumer's DTO is mostly just boilerplate `pom.xml` file.
-In the todoapp this can be found in the `todoapp-xsd` Maven module, whose `pom.xml` is structured as two profiles:
-
-[source,xml]
-----
-<project ... >
-    <artifactId>todoapp-xsd</artifactId>
-    <dependencies>
-        <dependency>
-            <groupId>${project.groupId}</groupId>
-            <artifactId>todoapp-app</artifactId>
-        </dependency>
-    </dependencies>
-    <profiles>
-        <profile>
-            <id>isis-xsd</id>
-            <activation>
-                <property>
-                    <name>!skip.isis-xsd</name>
-                </property>
-            </activation>
-            ...
-        </profile>
-        <profile>
-            <id>xjc</id>
-            <activation>
-                <property>
-                    <name>!skip.xjc</name>
-                </property>
-            </activation>
-            ...
-        </profile>
-    </profiles>
-</project>
-----
-
-The `isis-xsd` profile generates the XSD using the xref:../rgmvn/rgmvn.adoc#_rgmvn_xsd[`xsd` goal] of Isis' maven plugin:
-
-[source,xml]
-----
-<build>
-    <plugins>
-        <plugin>
-            <groupId>org.apache.isis.tool</groupId>
-            <artifactId>isis-maven-plugin</artifactId>
-            <version>${isis.version}</version>
-            <configuration>
-                <appManifest>todoapp.dom.ToDoAppDomManifest</appManifest>
-                <jaxbClasses>
-                    <jaxbClass>todoapp.app.viewmodels.todoitem.v1.ToDoItemV1_1</jaxbClass>
-                </jaxbClasses>
-                <separate>false</separate>
-                <commonSchemas>false</commonSchemas>
-            </configuration>
-            <dependencies>
-                <dependency>
-                    <groupId>${project.groupId}</groupId>
-                    <artifactId>todoapp-dom</artifactId>
-                    <version>${project.version}</version>
-                </dependency>
-                <dependency>
-                    <groupId>com.google.guava</groupId>
-                    <artifactId>guava</artifactId>
-                    <version>16.0.1</version>
-                </dependency>
-            </dependencies>
-            <executions>
-                <execution>
-                    <phase>generate-sources</phase>
-                    <goals>
-                        <goal>xsd</goal>
-                    </goals>
-                </execution>
-            </executions>
-        </plugin>
-        <plugin>
-            <artifactId>maven-assembly-plugin</artifactId>
-            <version>2.5.3</version>
-            <configuration>
-                <descriptor>src/assembly/dep.xml</descriptor>
-            </configuration>
-            <executions>
-                <execution>
-                    <id>create-archive</id>
-                    <phase>package</phase>
-                    <goals>
-                        <goal>single</goal>
-                    </goals>
-                </execution>
-            </executions>
-        </plugin>
-    </plugins>
-</build>
-----
-
-The `todoapp.dom.ToDoAppDomManifest` is a cut-down version of the app manifest that identifies only the `dom` domain services.
-
-The `xjc` profile, meanwhile, uses the `maven-jaxb2-plugin` (a wrapper around the `schemagen` JDK tool) to generate a DTO from the XSD generated by the preceding profile:
-
-[source,xml]
-----
-<build>
-    <plugins>
-        <plugin>
-            <groupId>org.jvnet.jaxb2.maven2</groupId>
-            <artifactId>maven-jaxb2-plugin</artifactId>
-            <version>0.12.3</version>
-            <executions>
-                <execution>
-                    <id>xjc-generate</id>
-                    <phase>generate-sources</phase>
-                    <goals>
-                        <goal>generate</goal>
-                    </goals>
-                </execution>
-            </executions>
-            <configuration>
-                <removeOldOutput>true</removeOldOutput>
-                <schemaDirectory>
-                    target/generated-resources/isis-xsd/viewmodels.app.todoapp
-                </schemaDirectory>
-                <schemaIncludes>
-                    <schemaInclude>todoitem/v1/Dto.xsd</schemaInclude>
-                </schemaIncludes>
-                <bindingDirectory>src/main/resources</bindingDirectory>
-                <bindingIncludes>
-                    <bindingInclude>binding.xml</bindingInclude>
-                </bindingIncludes>
-                <catalog>src/main/resources/catalog.xml</catalog>
-            </configuration>
-        </plugin>
-        <plugin>
-            <groupId>org.codehaus.mojo</groupId>
-            <artifactId>build-helper-maven-plugin</artifactId>
-            <version>1.9.1</version>
-            <executions>
-                <execution>
-                    <id>add-source</id>
-                    <phase>generate-sources</phase>
-                    <goals>
-                        <goal>add-source</goal>
-                    </goals>
-                    <configuration>
-                    <sources>
-                        <source>target/generated-sources/xjc</source>
-                    </sources>
-                    </configuration>
-                </execution>
-            </executions>
-        </plugin>
-    </plugins>
-</build>
-----

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_programming-model.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_programming-model.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_programming-model.adoc
deleted file mode 100644
index 2fd3a82..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_programming-model.adoc
+++ /dev/null
@@ -1,89 +0,0 @@
-[[_ugbtb_view-models_programming-model]]
-= Programming Model
-: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/
-
-
-
-This section describes how to implement view models.
-
-Fundamentally all view models' state is serialized into
-a string memento; this memento is then held by the client (browser) in the form of a URL.  As you might imagine, this
-URL can become quite long, but Apache Isis offers a mechanism (the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UrlEncodingService[`UrlEncodingService`]) if it exceeds the maximum length for a URL
-(2083 characters).  Also, of course, this string memento must only contain characters that it is valid for use within
-a URL.
-
-While the underlying technique is the same irrespective of use case, the programming model provides various ways of
-defining a view model so that the original intent is not lost.  They are:
-
-.View model programming model
-[cols="1a,4a,2a", options="header"]
-|===
-
-| Use case
-| Code
-| Description
-
-
-| External entity
-|[source,java]
-----
-@DomainObject(nature=Nature.EXTERNAL_ENTITY)
-public class CustomerRecordOnSAP { ... }
-----
-|Annotated with xref:../rgant/rgant.adoc#_rgant-DomainObject_nature[`@DomainObject#nature()`] and a nature of `EXTERNAL_ENTITY`, with memento derived automatically from the properties of the domain object.  Collections are ignored, as are any properties annotated as xref:../rgant/rgant.adoc#_rgant-Property_notPersisted[not persisted].
-
-| In-memory entity
-|[source,java]
-----
-@DomainObject(nature=Nature.INMEMORY_ENTITY)
-public class Log4JAppender { ... }
-----
-|As preceding, but using a nature of `INMEMORY_ENTITY`.
-
-|Application view model
-|[source,java]
-----
-@DomainObject(nature=Nature.VIEW_MODEL)
-public class Dashboard { ... }
-----
-|As preceding, but using a nature of `VIEW_MODEL`.
-
-|Application view model
-|
-[source,java]
-----
-@ViewModel
-public class Dashboard { ... }
-----
-
-|Annotated with xref:../rgant/rgant.adoc#_rgant-ViewModel[`@ViewModel`] annotation (effectively just an alias)' memento is as preceding: from "persisted" properties, collections ignored
-
-|Application view model
-|
-[source,java]
-----
-public class ExcelUploadManager implements ViewModel {
-  public String viewModelMemento() { ... }
-  public void viewModelInit(String memento) { ... }
-}
-|Implement xref:../rgcms/rgcms.adoc#_rgcms_classes_super_ViewModel[`ViewModel`] interface.  The memento is as defined by the
-interface's methods: the programmer has full control (but also full responsibility) for the string memento.
-
-|DTO
-|
-[source,java]
-----
-@XmlRootElement("customer")
-public class CustomerDto { ... }
-----
-|Annotate using JAXB xref:../rgant/rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`] annotation.  Memento
-derived automatically by serializing the XML graph as implied by the JAXB annotations.  Note that (unlike `@ViewModel`
-et al) this state _can_ include collections.
-|===
-
-JAXB-annotated DTOs are discussed in more detail immediately xref:rg.adoc#_ugbtb_view-models_jaxb[below].
-
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugbtb/ugbtb.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/ugbtb.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/ugbtb.adoc
index c03eedb..3d3c365 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/ugbtb.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/ugbtb.adoc
@@ -43,7 +43,6 @@ The remaining guides are:
 * xref:../cgcom/cgcom.adoc#[Committers' Guide] (release procedures and related practices)
 
 
-include::_ugbtb_view-models.adoc[leveloffset=+1]
 include::_ugbtb_decoupling.adoc[leveloffset=+1]
 include::_ugbtb_i18n.adoc[leveloffset=+1]
 include::_ugbtb_headless-access.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_available-domain-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_available-domain-services.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_available-domain-services.adoc
new file mode 100644
index 0000000..1331977
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_available-domain-services.adoc
@@ -0,0 +1,18 @@
+[[_ugfun_available-domain-services]]
+= Available Domain Services
+: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/
+
+
+There are a number of domain services/modules already implemented for you to use directly within your applications.
+Some of these are provided by the framework, while others are third-party (but still open source).
+
+This chapter surveys some of the domain services currently available.
+
+
+include::_ugfun_available-domain-services_framework-provided.adoc[leveloffset=+1]
+include::_ugfun_available-domain-services_isis-addons.adoc[leveloffset=+1]
+include::_ugfun_available-domain-services_incode-catalog.adoc[leveloffset=+1]
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_available-domain-services_framework-provided.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_available-domain-services_framework-provided.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_available-domain-services_framework-provided.adoc
new file mode 100644
index 0000000..11a3622
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_available-domain-services_framework-provided.adoc
@@ -0,0 +1,107 @@
+[[_ugfun_available-domain-services_framework-provided]]
+= Framework-provided Services
+: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/
+
+
+Most framework domain services are API: they exist to provide support functionality to the application's domain objects and services.
+In this case an implementation of the service will be available, either by Apache Isis itself or by Isis Addons (non ASF).
+
+Some framework domain services are SPI: they exist primarily so that the application can influence the framework's behaviour.
+In these cases there is (usually) no default implementation; it is up to the application to provide an implementation.
+
+
+General purpose:
+
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`]; mostly deprecated, replaced by:
+** xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ClockService[`ClockService`]
+** xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ConfigurationService[`ConfigurationService`]
+** xref:../rgsvc/rgsvc.adoc#_rgsvc_api_MessageService[`MessageService`]
+** xref:../rgsvc/rgsvc.adoc#_rgsvc_api_RepositoryService[`RepositoryService`]
+** xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ServiceRegistry[`ServiceRegistry`]
+** xref:../rgsvc/rgsvc.adoc#_rgsvc_api_TitleService[`TitleService`]
+** xref:../rgsvc/rgsvc.adoc#_rgsvc_api_UserService[`UserService`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_IsisJdoSupport[`IsisJdoSupport`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EmailService[`EmailService`]
+
+Commands/Interactions/Background/Auditing/Publishing/Profiling:
+
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`] (SPI) (deprecated)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditerService`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BackgroundService[`BackgroundService`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[`BackgroundCommandService`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`] (SPI) (deprecated)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublisherService[`PublishererService`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_MetricsService[`MetricsService`]
+
+
+Information Sharing:
+
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_Scratchpad[`Scratchpad`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ActionInvocationContext[`ActionInvocationContext`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_QueryResultsCache[`QueryResultsCache`]
+
+UserManagement:
+
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UserProfileService[`UserProfileService`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UserRegistrationService[`UserRegistrationService`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_EmailNotificationService[`EmailNotificationService`] (SPI)
+
+Bookmarks and Mementos:
+
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_MementoService[`MementoService`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DeepLinkService[`DeepLinkService`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_JaxbService[`JaxbService`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_XmlSnapshotService[`XmlSnapshotService`]
+
+Layout and UI Management:
+
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_GridLoaderService[`GridLoaderService`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_GridService[`GridService`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_GridSystemService[`GridSystemService`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_HomePageProviderService[`HomePageProviderService`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_HintStore[`HintStore`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_LayoutService[`LayoutService`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_RoutingService[`RoutingService`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UrlEncodingService[`UrlEncodingService`] (SPI)
+
+REST Support:
+
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_AcceptHeaderService[`AcceptHeaderService`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_SwaggerService[`SwaggerService`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`] (SPI)
+
+Metamodel:
+
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ApplicationFeatureRepository[`ApplicationFeatureRepository`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_MetamodelService[`MetamodelService`]
+
+Other API:
+
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_FixtureScriptsDefault[`FixtureScriptsDefault`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_GuiceBeanProvider[`GuiceBeanProvider`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_SudoService[`SudoService`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_TransactionService[`TransactionService`]
+
+Other SPI:
+
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ClassDiscoveryService[`ClassDiscoveryService`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ErrorReportingService[`ErrorReportingService`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_EventSerializer[`EventSerializer`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ExceptionRecognizer[`ExceptionRecognizer`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_FixtureScriptsSpecificationProvider[`FixtureScriptsSpecificationProvider`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_LocaleProvider[`LocaleProvider`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_TranslationService[`TranslationService`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_TranslationsResolver[`TranslationsResolver`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_TranslationsResolver[`TranslationsResolver`] (SPI)
+
+
+A full list of services can be found in the xref:../rgsvc/rgsvc.adoc#_rgsvc[Domain Services] reference guide.
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_available-domain-services_incode-catalog.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_available-domain-services_incode-catalog.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_available-domain-services_incode-catalog.adoc
new file mode 100644
index 0000000..50bc834
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_available-domain-services_incode-catalog.adoc
@@ -0,0 +1,31 @@
+[[_ugfun_available-domain-services_incode-catalog]]
+= Incode Catalog
+: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/
+
+
+The link:http://catalog.incode.org[Incode Catalog] website also provides a number of reusable modules, focusing on business logic for generic subdomains.
+
+This section surveys the functionality available.
+
+
+[WARNING]
+====
+Note that the Incode Catalog, although maintained by Apache Isis committers, are not part of the ASF.
+====
+
+
+
+The modules themselves fall into a number of broader groups:
+
+* modules that provide standalone domain entities (and supporting services) for a particular subdomain +
++
+The http://github.com/incodehq/incode-module-alias[alias], http://github.com/incodehq/incode-module-classification[classification], http://github.com/incodehq/incode-module-commchannel[commchannel], http://github.com/incodehq/incode-module-communications[communications], http://github.com/incodehq/incode-module-country[country], http://github.com/incodehq/incode-module-docfragment[docfragment],
+http://github.com/incodehq/incode-module-document[document] and http://github.com/incodehq/incode-module-document[note] modules fall into this category.
+
+* modules that provide developer/testing utilities +
++
+The http://github.com/incodehq/incode-module-fixturesupport[fixturesupport], http://github.com/incodehq/incode-module-integtestsupport[integtestsupport] and http://github.com/incodehq/incode-module-unittestsupport[unittestsupport] modules fall into this category.
+
+Each of the modules has a full README and demo application demonstrating their usage.  The sections below briefly outline the capabilities of these modules.

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_available-domain-services_isis-addons.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_available-domain-services_isis-addons.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_available-domain-services_isis-addons.adoc
new file mode 100644
index 0000000..d7906a3
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_available-domain-services_isis-addons.adoc
@@ -0,0 +1,41 @@
+[[_ugfun_available-domain-services_isis-addons]]
+= Isis Add-ons
+: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/
+
+
+The link:http://www.isisaddons.org[Isis Addons] website provides a number of reusable modules for Apache Isis, focusing either on specific technologies or in technical cross-cutting concerns.
+Some of these modules implement SPIs defined by the framework.
+
+
+[WARNING]
+====
+Note that Isis Addons, although maintained by Apache Isis committers, are not part of the ASF.
+====
+
+
+
+The modules themselves fall into a number of broader groups:
+
+* modules that provide an implementations of SPI defined by Apache Isis +
++
+where Apache Isis has hooks to use the service if defined by provides no implementations of its own. +
++
+The http://github.com/isisaddons/isis-module-command[command], http://github.com/isisaddons/isis-module-audit[auditer], http://github.com/isisaddons/isis-module-publishmq[publisher], http://github.com/isisaddons/isis-module-security[security]  and http://github.com/isisaddons/isis-module-sessionlogger[sessionlogger] modules fall into this category.  Typically the domain objects themselves wouldn't interact with these services
+
+* modules that provide standalone domain services with their own API and implementation +
++
+These are simply intended to be used by domain objects. +
++
+The http://github.com/isisaddons/isis-module-docx[docx], http://github.com/isisaddons/isis-module-excel[excel], http://github.com/isisaddons/isis-module-freemarker[freemarker], http://github.com/isisaddons/isis-module-pdfbox[pdfbox], http://github.com/isisaddons/isis-module-settings[settings], http://github.com/isisaddons/isis-module-servletapi[servletapi], http://github.com/isisaddons/isis-module-stringinterpolator[stringinterpolator] and http://github.com/isisaddons/isis-module-xdocreport[xdocreport] fall into this category.
+
+* modules that provide standalone domain entities (and supporting services) for a particular subdomain +
++
+The http://github.com/isisaddons/isis-module-tags[tags] module falls into this category
+
+* modules that provide developer/testing utilities +
++
+The http://github.com/isisaddons/isis-module-fakedata[fakedata] module provides fakedata for unit- and integration testing.
+
+Each of the modules has a full README and demo application demonstrating their usage.  The sections below briefly outline the capabilities of these modules.

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks.adoc
new file mode 100644
index 0000000..8c61796
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks.adoc
@@ -0,0 +1,23 @@
+[[_ugfun_building-blocks]]
+= Building Blocks
+: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/
+
+In this section we run through the main building blocks that make up an Apache Isis application.
+
+include::_ugfun_building-blocks_metamodel.adoc[leveloffset=+1]
+
+include::_ugfun_building-blocks_types-of-domain-objects.adoc[leveloffset=+1]
+
+include::_ugfun_building-blocks_identifiers.adoc[leveloffset=+1]
+
+include::_ugfun_building-blocks_object-members.adoc[leveloffset=+1]
+
+include::_ugfun_building-blocks_events.adoc[leveloffset=+1]
+
+include::_ugfun_building-blocks_identifiers.adoc[leveloffset=+1]
+
+nclude::_ugfun_building-blocks_modules.adoc[leveloffset=+1]
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_events.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_events.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_events.adoc
new file mode 100644
index 0000000..ded8c28
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_events.adoc
@@ -0,0 +1,79 @@
+[[_ugfun_building-blocks_events]]
+= Events
+: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/
+
+
+When the framework renders a domain object, and as the end-user interacts with the domain object, the framework it emits multiple events using the intra-process xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[event bus].
+These events enable other domain services (possibly in other modules) to influence how the domain object is rendered, or to perform side-effects or even veto an action invocation.
+
+[TIP]
+====
+It is also possible to simulate the rendering of a domain object by way of the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`].
+This
+====
+
+To receive the events, the domain service should subscribe to the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`], and implement an appropriately annotated method to receive the events.
+
+The framework has several categories of events: domain events, UI events and lifecycle events.
+These are explored in the sections below.
+
+
+
+== Domain Events
+Domain events are fired for each object member (property, collection or action).
+
+By default, rendering a property causes a `PropertyDomainEvent` to be fired, though the xref:../rgant/rgant.adoc#_rgant_Property_domainEvent[`@Property#domainEvent()`] attribute allows a custom subclass to be specified if necessary.
+Similarly, rendering a collection causes a `CollectionDomainEvent` to be fired, and rendering an action causes an `ActionDomainEvent` to be fired.
+
+In fact, each event can be fired up to five times, with the event's `getEventPhase()` method indicating to the subscriber the phase:
+
+* *hide* phase allows the subscriber to hide the member
+
+* *disable* phase allows the subscriber to disable the member. +
+
+For a property this makes it read-only; for an action this makes it "greyed out".
+(Collections are implicitly read-only).
+
+* *validate* phase allows the subscriber to validate the proposed change.
+
+For a property this means validating the proposed new value of the property; for an action this means validating the action parameter arguments.
+For example, a referential integrity restrict could be implemented here.
+
+* *executing* phase is prior to the actual property edit/action invocation, allowing the subscriber to perform side-effects. +
+
+For example, a cascade delete could be implemented here.
+
+* *executed* phase is after the actual property edit/action invocation. +
++
+For example, a business audit event could be implemented here.
+
+
+For more details on the actual domain event classes, see the xref:../rgcms/rgcms.adoc#_rgcms_classes_domainevent[domain event] section of the relevant reference guide.
+
+
+
+
+== UI Events
+
+To allow the end-user to distinguish one domain object from another, it is rendered with a title and an icon.
+The icon informally identifies the type of the domain object, while the title identifies the instance.
+The title is not formally required to be a unique identify the object within its type, but it needs to be "unique enough" that a human user is able to distinguish one instance from another.
+
+Sometimes it's helpful for the icon to represent more than just the object's type; it might also indicate the state of an object.
+For example, a shipped `Order` might have a slightly different icon to a yet-to-be-shipped `Order`; or an overdue `Loan` might be distinguished separately from a
+
+Customisable icons
+
+and optionally with custom CSS
+Each domain object is rendered with a
+NOTE: FIXME
+
+
+For more details on the actual domain event classes, see the xref:../rgcms/rgcms.adoc#_rgcms_classes_uievent[UI event] section of the relevant reference guide.
+
+
+== Lifecycle Events
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_identifiers.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_identifiers.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_identifiers.adoc
new file mode 100644
index 0000000..c0bc698
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_identifiers.adoc
@@ -0,0 +1,14 @@
+[[_ugfun_building-blocks_identifiers]]
+= Identifiers
+: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/
+
+
+NOTE: FIXME
+
+
+
+include::_ugfun_building-blocks_identifiers_title-and-icon.adoc[leveloffset=+1]
+
+include::_ugfun_building-blocks_identifiers_oid.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_identifiers_oid.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_identifiers_oid.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_identifiers_oid.adoc
new file mode 100644
index 0000000..b4df70a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_identifiers_oid.adoc
@@ -0,0 +1,47 @@
+[[_ugfun_building-blocks_identifiers_oid]]
+= OIDs
+: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/
+
+
+As well as defining a xref:../ugfun/ugfun.adoc#__ugfun_building-blocks_metamodel[metamodel] of the structure (domain classes) of its domain objects, Apache Isis also manages the runtime instances of said domain objects.
+
+When a domain entity is recreated from the database, the framework keeps track of its identity through an "OID": an object identifier.
+Fundamentally this is a combination of its type (domain class), along with an identifier.
+You can think of it as its "primary key", except across all domain entity types.
+
+For portability and resilience, though, the object type is generally an alias for the actual domain class: thus "customers.CUS", say, rather than "com.mycompany.myapp.customers.Customer".
+This is derived from an annotation.
+The identifier meanwhile is always converted to a string.
+
+Although simple, the OID is an enormously powerful concept: it represents a URI to any domain object managed by a given Apache Isis application.
+With it, we have the ability to lookup any arbitrary domain objects.
+
+Some examples:
+
+* an OID allows sharing of information between users, eg as a deep link to be pasted into an email.
+
+* the information within an OID could be converted into a barcode, and stamped onto a PDF form.
+When the PDF is scanned by the mail room, the barcode could be read to attach the correspondence to the relevant domain object.
+
+* as a handle to any object in an audit record, as used by xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditerService`] or xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`] (the latter deprecated);
+
+* similarly within implementations of xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] to persist `Command`
+objects
+
+* similarly within implementations of xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`]
+to persist published action invocations
+
+* and of course both the xref:../ugvro/ugvro.adoc#[RestfulObjects viewer] and
+xref:../ugvw/ugvw.adoc#[Wicket viewer]
+use the oid tuple to look up, render and allow the user to interact with domain objects.
+
+Although the exact content of an OID should be considered opaque by domain objects, it is possible for domain objects to obtain OIDs.
+These are represented as `Bookmark`s, obtained from the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`].
+Deep links meanwhile can be obtained from the xref:../rgant/rgant.adoc#_rgant-DeepLinkService[`@DeepLinkService`].
+
+OIDs can also be converted into XML format, useful for integration scenarios.
+The xref:../rgcms/rgcms.adoc#_rgcms_schema-common[common schema] XSD defines the `oidDto` complex type for precisely this purpose.
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_identifiers_title-and-icon.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_identifiers_title-and-icon.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_identifiers_title-and-icon.adoc
new file mode 100644
index 0000000..356abe8
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_identifiers_title-and-icon.adoc
@@ -0,0 +1,27 @@
+[[_ugfun_building-blocks_identifiers_title-and-icon]]
+= Title and Icon
+: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/
+
+
+NOTE: FIXME
+
+
+
+To allow the end-user to distinguish one domain object from another, it is rendered with a title and an icon.
+The icon informally identifies the type of the domain object, while the title identifies the instance.
+The title is not formally required to be a unique identify the object within its type, but it needs to be "unique enough" that a human user is able to distinguish one instance from another.
+
+Sometimes it's helpful for the icon to represent more than just the object's type; it might also indicate the state of an object.
+For example, a shipped `Order` might have a slightly different icon to a yet-to-be-shipped `Order`; or an overdue `Loan` might be distinguished separately from a
+
+Customisable icons
+
+and optionally with custom CSS
+Each domain object is rendered with a
+NOTE: FIXME
+
+
+For more details on the actual domain event classes, see the xref:../rgcms/rgcms.adoc#_rgcms_classes_uievent[UI event] section of the relevant reference guide.
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_metamodel.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_metamodel.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_metamodel.adoc
new file mode 100644
index 0000000..7d5731b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_metamodel.adoc
@@ -0,0 +1,32 @@
+[[_ugfun_building-blocks_metamodel]]
+= A MetaModel
+: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/
+
+
+At its core, Apache Isis is a metamodel that is built at runtime from the domain classes (eg `Customer.java`), along with optional supporting metadata (eg `Customer.layout.xml`).
+
+The contents of this metamodel is inferred from the Java classes discovered on the classpath: the entities and supporting services, as well the members of those classes.
+The detail of the metamodel is generally explicit, usually represented by Java annotations such as `@Title` or `@Action`.
+Notably the metamodel is xref:../ugbtb/ugbtb.adoc#_ugbtb_programming-model[extensible]; it is possible to teach Apache Isis new programming conventions/rules (and conversely to remove those that are built in).
+
+Most of the annotations recognized by the framework are defined by the Apache Isis framework itself.
+For example the `@Title` annotation -- which identifies how the framework should derive a human-readable label for each rendered domain object -- is part of the `org.apache.isis.applib.annotations` package.
+However the framework also recognizes certain other JEE annotations such as `@javax.inject.Inject` (used for dependency injection).
+
+The framework uses DataNucleus for its persistence mechanism.
+This is an ORM that implements the JDO and JPA APIs, and which can map domain objects either to an RDBMS or to various NoSQL objectstores such as MongoDB or Neo4J.
+Apache Isis recognizes a number of the JDO annotations such as `@javax.jdo.annotations.Column(allowsNull=...)`.
+
+In addition, the framework builds up the metamodel for each domain object using
+xref:../ugvw/ugvw.adoc#_ugvw_layout[layout hints], such as `Customer.layout.xml`.
+These provide metadata such as grouping elements of the UI together, using multi-column layouts, and so on.
+The layout file can be modified while the application is still running, and are picked up automatically; a useful way to speed up feedback.
+
+[TIP]
+====
+At the time of writing Apache Isis only recognizes and supports the JDO API, though we expect JPA to be supported in the future.
+====
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_modules.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_modules.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_modules.adoc
new file mode 100644
index 0000000..40dbca0
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_modules.adoc
@@ -0,0 +1,15 @@
+[[_ugfun_building-blocks_modules]]
+= Modules
+: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/
+
+
+We tend to use Maven modules as a way to group related domain objects together; we can then reason about all the classes in that module as a single unit.
+By convention there will be a single top-level package corresponding to the module.
+
+For example, the (non-ASF) link:https://github.com/incodehq/incode-module-document[Document module] (part of the link:http://catalog.incode.org[Incode Catalog]) has a top-level package of `org.incode.module.document`.
+Within the module there may be various subpackages, but its the module defines the namespace.
+
+In the same way that the Java module act as a namespace for domain objects, it's good practice to map domain entities to their own (database) schemas.
+

[35/58] [abbrv] isis git commit: object titles and icons; fixing links

[da...@apache.org]

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_scoped-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_scoped-services.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_scoped-services.adoc
new file mode 100644
index 0000000..61c48ff
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_scoped-services.adoc
@@ -0,0 +1,23 @@
+[[_ugfun_programming-model_domain-services_scoped-services]]
+= Scoped services
+: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/
+
+
+By default all domain services are considered to be singletons, and thread-safe.
+
+Sometimes though a service's lifetime is applicable only to a single request; in other words it is request-scoped.
+
+The CDI annotation xref:../rgant/rgant.adoc#_rgant-RequestScoped[`@javax.enterprise.context.RequestScoped`] is used to indicate this fact:
+
+[source,java]
+----
+@javax.enterprise.context.RequestScoped
+public class MyService extends AbstractService {
+    ...
+}
+----
+
+The framework provides a number of request-scoped services, include a xref:../rgsvc/rgsvc.adoc#_rgsvc_api_Scratchpad[`Scratchpad`] service query results caching through the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_QueryResultsCache[`QueryResultsCache`], and support for co-ordinating bulk actions through the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ActionInvocationContext[`ActionInvocationContext`] service.  See the xref:../rgsvc/rgsvc.adoc#[domain services] reference guide for further details.
+

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_mixins.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_mixins.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_mixins.adoc
index 1a0a9a3..d6c3f45 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_mixins.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_mixins.adoc
@@ -6,12 +6,11 @@
 :_imagesdir: images/
 
 
-
+A xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_types-of-domain-objects_mixins[mixin] acts like a trait or extension method, allowing one module to contribute behaviour or derived state to another object.
 
 Syntactically, a mixin is defined using either the xref:../rgant/rgant.adoc#_rgant_Mixin[`@Mixin`] annotation or using xref:../rgant/rgant.adoc#_rgant_DomainObject_nature[`@DomainObject#nature()`] attribute (specifying a nature of `Nature.MIXIN`).
 
 
-
 [source,java]
 ----
 @Mixin(method="coll")                                       // <1>
@@ -41,306 +40,18 @@ This could also be an interface.
 This requires that the action has safe semantics, ie does not alter state/no side-effects.
 
 
+include::_ugfun_programming-model_mixins_contributed-collection.adoc[leveloffset=+1]
 
+include::_ugfun_programming-model_mixins_contributed-property.adoc[leveloffset=+1]
 
+include::_ugfun_programming-model_mixins_contributed-action.adoc[leveloffset=+1]
 
+include::_ugfun_programming-model_mixins_inferred-name.adoc[leveloffset=+1]
 
+include::_ugfun_programming-model_mixins_nested-static-classes  .adoc[leveloffset=+1]
 
-''''
-''''
-
-== Contributed services
-
-Contributed services provide many of the same benefits as xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_mixins[mixins];
-indeed mixins are an evolution and refinement of the contributions concept.
-
-[WARNING]
-====
-It's possible that contributions may be deprecated and eventually removed in a future version of the framework, to be replaced entirely by mixins.
-====
-
-The main difference between contributed services and mixins is that the actions of a contributed service will
-contribute to _all_ the parameters of its actions, whereas a mixin only contributes to the type accepted in its
-constructor.  Also, contributed services are long-lived
-singletons, whereas mixins are instantiated as required (by the framework) and then discarded almost immediately.
-
-[NOTE]
-====
-There's further useful information on contributed services in the reference guide, discussing the xref:../rgant/rgant.adoc#_rgant-DomainService_nature[@DomainService#nature()] attribute, for the `NatureOfService.VIEW_CONTRIBUTIONS_ONLY` nature.
-====
-
-
-=== Syntax
-
-Any n-parameter action provided by a service will automatically be contributed to the list of actions for each of its (entity) parameters. From the viewpoint of the entity the action is called a contributed action.
-
-For example, given a service:
-
-[source,java]
-----
-public interface Library {
-    public Loan borrow(Loanable l, Borrower b);
-}
-----
-
-and the entities:
-
-[source,java]
-----
-public class Book implements Loanable { ... }
-----
-
-and
-
-[source,java]
-----
-public class LibraryMember implements Borrower { ... }
-----
-
-then the `borrow(...)` action will be contributed to both `Book` and to `LibraryMember`.
-
-This is an important capability because it helps to decouple the concrete classes from the services.
-
-If necessary, though, this behaviour can be suppressed by annotating the service action with `@org.apache.isis.applib.annotations.NotContributed`.
-
-For example:
-
-[source,java]
-----
-public interface Library {
-    @NotContributed
-    public Loan borrow(Loanable l, Borrower b);
-}
-----
+include::_ugfun_programming-model_mixins_programmatic-usage  .adoc[leveloffset=+1]
 
-If annotated at the interface level, then the annotation will be inherited by every concrete class. Alternatively the annotation can be applied at the implementation class level and only apply to that particular implementation.
-
-Note that an action annotated as being `@NotContributed` will still appear in the service menu for the service. If an action should neither be contributed nor appear in service menu items, then simply annotate it as `@Hidden`.
-
-
-## Contributed Action
-
-NOTE: FIXME
-
-## Contributed Property
-
-NOTE: FIXME
-
-## Contributed Collection
-
-NOTE: FIXME
-
-
-
-
-
-== Contributed Collection
-
-The example below shows how to contribute a collection:
-
-[source,java]
-----
-@Mixin
-public class DocumentHolderDocuments {
-
-    private final DocumentHolder holder;
-    public DocumentHolderDocuments(DocumentHolder holder) { this.holder = holder; }
-
-    @Action(semantics=SemanticsOf.SAFE)                         // <1>
-    @ActionLayout(contributed = Contributed.AS_ASSOCIATION)     // <2>
-    @CollectionLayout(render = RenderType.EAGERLY)
-    public List<Document> documents() {                         // <3>
-        ...
-    }
-    public boolean hideDocuments() { ... }                      // <4>
-}
-----
-<1> required; actions that have side-effects cannot be contributed as collections
-<2> required; otherwise the mixin will default to being rendered as an action
-<3> must accept no arguments.
-    The mixin is a collection rather than a property because the return type is a collection, not a scalar.
-<4> supporting methods follow the usual naming conventions.
-    (That said, in the case of collections, because the collection is derived/read-only, the only supporting method that is relevant is `hideXxx()`).
-
-The above will result in a contributed collection for all types that implement/extend from `DocumentHolder` (so is probably for a mixin across modules).
-
-
-
-== Contributed Property
-
-Contributed properties are defined similarly, for example:
-
-[source,java]
-----
-@Mixin
-public class DocumentHolderMostRecentDocument {
-
-    private final DocumentHolder holder;
-    public DocumentHolderDocuments(DocumentHolder holder) { this.holder = holder; }
-
-    @Action(semantics=SemanticsOf.SAFE)                         // <1>
-    @ActionLayout(contributed = Contributed.AS_ASSOCIATION)     // <2>
-    public Document> mostRecentDocument() {                     // <3>
-        ...
-    }
-    public boolean hideMostRecentDocument() { ... }             // <4>
-}
-----
-<1> required; actions that have side-effects cannot be contributed as collections
-<2> required; otherwise the mixin will default to being rendered as an action
-<3> must accept no arguments.
-    The mixin is a property rather than a collection because the return type is a scalar.
-<4> supporting methods follow the usual naming conventions.
-    (That said, in the case of properties, because the property is derived/read-only, the only supporting method that is relevant is `hideXxx()`).
-
-
-== Contributed Action
-
-Contributed properties are defined similarly, for example:
-
-[source,java]
-----
-@Mixin
-public class DocumentHolderAddDocument {
-
-    private final DocumentHolder holder;
-    public DocumentHolderDocuments(DocumentHolder holder) { this.holder = holder; }
-
-    @Action()
-    @ActionLayout(contributed = Contributed.AS_ACTION)          // <1>
-    public Document> addDocument(Document doc) {
-        ...
-    }
-    public boolean hideAddDocument() { ... }                    // <2>
-}
-----
-<1> recommended
-<2> supporting methods follow the usual naming conventions.
-
-
-== Inferred Name
-
-Where the mixin follows the naming convention `SomeType_mixinName` then the method name can be abbreviated to "$$".
-The mixin name is everything after the last '_'.
-
-For example:
-
-[source,java]
-----
-@Mixin
-public class DocumentHolder_documents {
-
-    private final DocumentHolder holder;
-    public DocumentHolder_documents(DocumentHolder holder) { this.holder = holder; }
-
-    @Action(semantics=SemanticsOf.SAFE)
-    @ActionLayout(contributed = Contributed.AS_ASSOCIATION)
-    @CollectionLayout(render = RenderType.EAGERLY)
-    public List<Document> $$() {                                    // <1>
-        ...
-    }
-    public boolean hide$$() { ... }                                 // <2>
-}
-----
-<1> using "$$" as the reserved method name
-<2> supporting methods as usual
-
-The character "$" is also recognized as a separator between the mixin type and mixin name.
-This is useful for mixins implemented as nested static types, discussed below.
-
-
-== As Nested Static Classes
-
-As noted in the introduction, while mixins were originally introduced as a means of allowing contributions from one module to the types of another module, they are also a convenient mechanism for grouping functionality/behaviour against a concrete type.
-All the methods and supporting methods end up in a single construct, and the dependency between that functionality and the rest of the object is made more explicit.
-
-When using mixins in this fashion, it is idiomatic to write the mixin as a nested static class, using the naming convention described above to reduce duplication.
-
-For example:
-
-[source,java]
-----
-public class Customer {
-
-    @Mixin
-    public static class placeOrder {                                            // <1>
-
-        private final Customer customer;
-        public documents(Customer customer) { this.customer = customer; }       // <2>
-
-        @Action
-        @ActionLayout(contributed = Contributed.AS_ACTION)
-        public List<Order> $$(Product p, int quantity) {                        // <3>
-            ...
-        }
-        public boolean hide$$() { ... }                                         // <4>
-        public String validate0$$(Product p) { ...  }
-    }
-}
-----
-<1> Prior to `1.13.2`, had to be prefixed by an "_"; this is no longer required because "$" is also recognized as a way of parsing the class name in order to infer the mixin's name (eg `Customer$placeOrder`).
-<2> typically contributed to concrete class
-<3> using the "$$" reserved name
-<4> supporting methods as usual
-
-
-Moreover, the mixin class can be capitalized if desired.
-Thus:
-
-[source,java]
-----
-public class Customer {
-
-    @Mixin
-    public static class PlaceOrder {                                            // <1>
-
-        private final Customer customer;
-        public documents(Customer customer) { this.customer = customer; }       // <2>
-
-        @Action
-        @ActionLayout(contributed = Contributed.AS_ACTION)
-        public List<Order> $$(Product p, int quantity) {                        // <3>
-            ...
-        }
-        public boolean hide$$() { ... }                                         // <4>
-        public String validate0$$(Product p) { ...  }
-    }
-}
-----
-
-
-In other words, all of the following are allowed:
-
-* `public static class Documents { ... }`
-* `public static class documents { ... }`
-* `public static class _Documents { ... }`
-* `public static class _documents { ... }`
-
-The reserved method name "$$" can also be changed using xref:../rgant/rgant.adoc#_rgant_Mixin_method[`@Mixin#method()`] or xref:../rgant/rgant.adoc#_rgant_DomainObject_mixinMethod[`@DomainObject#mixinMethod()`].
-
-
-
-
-
-
-
-
-== Programmatic usage
-
-When a domain object is rendered, the framework will automatically instantiate all required mixins and delegate to them
-dynamically.  If writing integration tests or fixtures, or (sometimes) just regular domain logic, then you may need to
-instantiate mixins directly.
-
-For this you can use the
-xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-creation-api[`DomainObjectContainer#mixin(...)`
-method.  For example:
-
-[source,java]
-----
-DocumentHolder_documents mixin = container.mixin(DocumentHolder_documents.class, customer);
-----
+include::_ugfun_programming-model_mixins_contributed-services  .adoc[leveloffset=+1]
 
-The xref:../ugtst/ugtst.adoc#__ugtst_integ-test-support_bootstrapping_IntegrationTestAbstract[`IntegrationTestAbstract`] and
-xref:../rgcms/rgcms.adoc#_rgcms_classes_super_FixtureScript[`FixtureScript`] classes both provide a `mixin(...)` convenience
-method.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_mixins_contributed-action.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_mixins_contributed-action.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_mixins_contributed-action.adoc
new file mode 100644
index 0000000..eec7692
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_mixins_contributed-action.adoc
@@ -0,0 +1,29 @@
+[[_ugfun_programming-model_mixins_contributed-action]]
+= Contributed Action
+
+: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/
+
+
+Contributed actions are defined similarly, for example:
+
+[source,java]
+----
+@Mixin(method="act")
+public class DocumentHolder_addDocument {
+
+    private final DocumentHolder holder;
+    public DocumentHolderDocuments(DocumentHolder holder) { this.holder = holder; }
+
+    @Action()
+    @ActionLayout(contributed = Contributed.AS_ACTION)          // <1>
+    public Document> act(Document doc) {
+        ...
+    }
+    public boolean hideAct() { ... }                            // <2>
+}
+----
+<1> recommended
+<2> supporting methods follow the usual naming conventions.
+

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_mixins_contributed-collection.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_mixins_contributed-collection.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_mixins_contributed-collection.adoc
new file mode 100644
index 0000000..d92f5d7
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_mixins_contributed-collection.adoc
@@ -0,0 +1,38 @@
+[[_ugfun_programming-model_mixins_contributed-collection]]
+= Contributed Collection
+
+: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/
+
+
+
+The example below shows how to contribute a collection:
+
+[source,java]
+----
+@Mixin(method="coll")
+public class DocumentHolder_documents {
+
+    private final DocumentHolder holder;
+    public DocumentHolderDocuments(DocumentHolder holder) { this.holder = holder; }
+
+    @Action(semantics=SemanticsOf.SAFE)                         // <1>
+    @ActionLayout(contributed = Contributed.AS_ASSOCIATION)     // <2>
+    @CollectionLayout(render = RenderType.EAGERLY)
+    public List<Document> coll() {                              // <3>
+        ...
+    }
+    public boolean hideColl() { ... }                           // <4>
+}
+----
+<1> required; actions that have side-effects cannot be contributed as collections
+<2> required; otherwise the mixin will default to being rendered as an action
+<3> must accept no arguments.
+The mixin is a collection rather than a property because the return type is a collection, not a scalar.
+<4> supporting methods follow the usual naming conventions.
+(That said, in the case of collections, because the collection is derived/read-only, the only supporting method that is relevant is `hideColl()`).
+
+The above will result in a contributed collection "documents" for all types that implement/extend from `DocumentHolder`.
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_mixins_contributed-property.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_mixins_contributed-property.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_mixins_contributed-property.adoc
new file mode 100644
index 0000000..491a03f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_mixins_contributed-property.adoc
@@ -0,0 +1,35 @@
+[[_ugfun_programming-model_mixins_contributed-property]]
+= Contributed Property
+
+: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/
+
+
+
+Contributed properties are defined similarly, for example:
+
+[source,java]
+----
+@Mixin(method="prop")
+public class DocumentHolder_mostRecentDocument {
+
+    private final DocumentHolder holder;
+    public DocumentHolderDocuments(DocumentHolder holder) { this.holder = holder; }
+
+    @Action(semantics=SemanticsOf.SAFE)                         // <1>
+    @ActionLayout(contributed = Contributed.AS_ASSOCIATION)     // <2>
+    public Document prop() {                                    // <3>
+        ...
+    }
+    public boolean hiderProp() { ... }                          // <4>
+}
+----
+<1> required; actions that have side-effects cannot be contributed as collections
+<2> required; otherwise the mixin will default to being rendered as an action
+<3> must accept no arguments.
+The mixin is a property rather than a collection because the return type is a scalar.
+<4> supporting methods follow the usual naming conventions.
+(That said, in the case of properties, because the property is derived/read-only, the only supporting method that is relevant is `hideProp()`).
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_mixins_contributed-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_mixins_contributed-services.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_mixins_contributed-services.adoc
new file mode 100644
index 0000000..93ab3ce
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_mixins_contributed-services.adoc
@@ -0,0 +1,46 @@
+[[_ugfun_programming-model_mixins_contributed-services]]
+= Contributed services (deprecated)
+
+: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/
+
+
+
+Contributed services are very similar to mixins; indeed mixins are an evolution and refinement of the contributions concept.
+As such, contributions should be considered as deprecated, and eventually removed in a future version of the framework, to be replaced entirely by mixins.
+
+The main difference between contributed services and mixins is that the actions of a contributed service will contribute to _all_ the parameters of its actions, whereas a mixin only contributes to the type accepted in its constructor.
+
+Also, contributed services are long-lived singletons, whereas mixins are instantiated as required (by the framework) and then discarded almost immediately.
+
+== Syntax
+
+Any n-parameter action provided by a service will automatically be contributed to the list of actions for each of its (entity) parameters.
+From the viewpoint of the entity the action is called a contributed action.
+
+For example, given a service:
+
+[source,java]
+----
+public interface Library {
+    public Loan borrow(Loanable l, Borrower b);
+}
+----
+
+and the entities:
+
+[source,java]
+----
+public class Book implements Loanable { ... }
+----
+
+and
+
+[source,java]
+----
+public class LibraryMember implements Borrower { ... }
+----
+
+then the `borrow(...)` action will be contributed to both `Book` and to `LibraryMember`.
+

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_mixins_inferred-name.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_mixins_inferred-name.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_mixins_inferred-name.adoc
new file mode 100644
index 0000000..9306218
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_mixins_inferred-name.adoc
@@ -0,0 +1,45 @@
+[[_ugfun_programming-model_mixins_inferred-name]]
+= Inferred Name
+
+: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/
+
+
+
+
+Where the mixin follows the naming convention `SomeType_mixinName` then the method name can be abbreviated, and the name of the member being contributed is inferred from the name of the class itself, beingeverything after the last '_'.
+
+The default abbreviation to "$$".
+
+For example:
+
+[source,java]
+----
+@Mixin
+public class DocumentHolder_documents {
+
+    private final DocumentHolder holder;
+    public DocumentHolder_documents(DocumentHolder holder) { this.holder = holder; }
+
+    @Action(semantics=SemanticsOf.SAFE)
+    @ActionLayout(contributed = Contributed.AS_ASSOCIATION)
+    @CollectionLayout(render = RenderType.EAGERLY)
+    public List<Document> $$() {                                    // <1>
+        ...
+    }
+    public boolean hide$$() { ... }                                 // <2>
+}
+----
+<1> using "$$" as the reserved method name
+<2> supporting methods as usual
+
+
+Alternatively, if the xref:../rgant/rgant.adoc#_rgant_Mixin_method[`@Mixin#method()`] attribute is specified, then this can nominate a different abbreviation.
+
+The examples above (for xref:../ugfun/ugfun.adoc#_ugfun_programming-model_mixins_contributed-property[property], xref:../ugfun/ugfun.adoc#_ugfun_programming-model_mixins_contributed-collection[collection] and xref:../ugfun/ugfun.adoc#_ugfun_programming-model_mixins_contributed-action[action]) demonstrate this.
+
+
+The character "$" is also recognized as a separator between the mixin type and mixin name.
+This is useful for mixins implemented as nested static types, discussed xref:../ugfun/ugfun.adoc#_ugfun_programming-model_mixins_nested-static-classes[below].
+

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_mixins_nested-static-classes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_mixins_nested-static-classes.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_mixins_nested-static-classes.adoc
new file mode 100644
index 0000000..4596a2c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_mixins_nested-static-classes.adoc
@@ -0,0 +1,78 @@
+[[_ugfun_programming-model_mixins_nested-static-classes]]
+= As Nested Static 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/
+
+
+
+As noted in the introduction, while mixins were originally introduced as a means of allowing contributions from one module to the types of another module, they are also a convenient mechanism for grouping functionality/behaviour against a concrete type.
+All the methods and supporting methods end up in a single construct, and the dependency between that functionality and the rest of the object is made more explicit.
+
+When using mixins in this fashion, it is idiomatic to write the mixin as a nested static class, using the naming convention described above to reduce duplication.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+
+    @Mixin(method="act")
+    public static class placeOrder {                                            // <1>
+
+        private final Customer customer;
+        public documents(Customer customer) { this.customer = customer; }       // <2>
+
+        @Action
+        @ActionLayout(contributed = Contributed.AS_ACTION)
+        public List<Order> act(Product p, int quantity) {                        // <3>
+            ...
+        }
+        public boolean hideAct() { ... }                                         // <4>
+        public String validate0Act(Product p) { ...  }
+    }
+}
+----
+<1> Prior to `1.13.2`, had to be prefixed by an "_"; this is no longer required because "$" is also recognized as a way of parsing the class name in order to infer the mixin's name (eg `Customer$placeOrder`).
+<2> typically contributed to concrete class
+<3> using the "$$" reserved name
+<4> supporting methods as usual
+
+
+The mixin class can also be capitalized if desired.
+Thus:
+
+[source,java]
+----
+public class Customer {
+
+    @Mixin(method="act")
+    public static class PlaceOrder {                                            // <1>
+
+        private final Customer customer;
+        public documents(Customer customer) { this.customer = customer; }       // <2>
+
+        @Action
+        @ActionLayout(contributed = Contributed.AS_ACTION)
+        public List<Order> act(Product p, int quantity) {                        // <3>
+            ...
+        }
+        public boolean hideAct() { ... }                                         // <4>
+        public String validate0Act(Product p) { ...  }
+    }
+}
+----
+
+
+In other words, all of the following are allowed:
+
+* `public static class Documents { ... }`
+* `public static class documents { ... }`
+* `public static class _Documents { ... }`
+* `public static class _documents { ... }`
+
+The reserved method name "$$" can also be changed using xref:../rgant/rgant.adoc#_rgant_Mixin_method[`@Mixin#method()`] or xref:../rgant/rgant.adoc#_rgant_DomainObject_mixinMethod[`@DomainObject#mixinMethod()`].
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_mixins_programmatic-usage.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_mixins_programmatic-usage.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_mixins_programmatic-usage.adoc
new file mode 100644
index 0000000..862d816
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_mixins_programmatic-usage.adoc
@@ -0,0 +1,26 @@
+[[_ugfun_programming-model_mixins_programmatic-usage]]
+= Programmatic 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/
+
+
+
+When a domain object is rendered, the framework will automatically instantiate all required mixins and delegate to them dynamically.
+If writing integration tests or fixtures, or (sometimes) just regular domain logic, then you may need to instantiate mixins directly.
+
+For this you can use the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-creation-api[`DomainObjectContainer#mixin(...)` method.
+
+For example:
+
+[source,java]
+----
+DocumentHolder_documents mixin = container.mixin(DocumentHolder_documents.class, customer);
+----
+
+The xref:../ugtst/ugtst.adoc#__ugtst_integ-test-support_bootstrapping_IntegrationTestAbstract[`IntegrationTestAbstract`] and xref:../rgcms/rgcms.adoc#_rgcms_classes_super_FixtureScript[`FixtureScript`] classes both provide a `mixin(...)` convenience method.
+
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_properties.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_properties.adoc
index 0ab9bad..b22a444 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_properties.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_properties.adoc
@@ -129,7 +129,7 @@ If this is omitted then whether editing is enabled or disabled is defined global
 [[__ugfun_programming-model_properties_ignoring-properties]]
 == Ignoring Properties
 
-By default Apache Isis will automatically render all properties in the xref:../ugvw/ugvw.adoc[UI] or in the xref:../ugvro/ugvro.adoc[REST API].
+By default Apache Isis will automatically render all properties in the xref:../ugvw/ugvw.adoc#[Wicket UI] or in the xref:../ugvro/ugvro.adoc[REST API].
 To get Apache Isis to ignore a property (exclude it from its metamodel), annotate the getter using `@Programmatic`.
 
 Similarly, you can tell JDO/DataNucleus to ignore a property using the `@javax.jdo.annotations.NotPersistent` annotation.

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models.adoc
index 37929da..0ff8781 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models.adoc
@@ -1,631 +1,28 @@
 [[_ugfun_programming-model_view-models]]
 = View Models
-
 :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/
 
 
+As described in the xref:../ugfun/ugfun.adoc#\_ugfun_building-blocks_types-of-domain-objects_view-models[introduction], view models are domain objects like domain entities, with behaviour and state.
+However, unlike domain entities, their state is _not_ persisted to a database but is instead serialized into its identifier (in effect, its URL).
 
+The framework provides two main ways to implement a view model:
 
-NOTE: FIXME - move the stuff from ugbtb here
-
-NOTE: FIXME - deprecate the @ViewModel stuff, emphasise using JAXB only
-
-
-
-
-[[__ugfun_building-blocks_view-models_typical-implementation]]
-== Typical Implementation
-
-Apache Isis offers several ways to implement view models, but the most flexible/powerful is to annotate the class using JAXB annotations.
-For example:
-
-[source,java]
-----
-@XmlRootElement(name = "invoiceRun")    // <1>
-@XmlType(
-        propOrder = {                   // <2>
-            ...
-        }
-)
-public class InvoiceRun {
-    ...
-}
-----
-<1> The JAXB `@XmlRootElement` annotation indicates this is a view model to Apache Isis, which then uses JAXB to serialize the state of the view model between interactions
-<2> All properties of the view model must be listed using the `XmlType#propOrder` attribute.
-
-Use JAXB elements such as `@XmlElement` for properties and the combination of `@XmlElementWrapper` and `@XmlElement` for collections.
-Properties can be ignored (for serialization) using `@XmlTransient`.
-
-
-''''
-''''
-
-[[_ugbtb_view-models_jaxb]]
-== JAXB-annotated View Models/DTOs
-
-As noted in the xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_view-models[introduction], view models can also be defined using JAXB annotations.
-The serialized form of these view models is therefore XML, which also enables these view models
-to act as DTOs.
-
-In case it's not obvious, these DTOs are still usable as "regular" view models; they will render in the xref:../ugvw/ugvw.adoc#[Wicket viewer] just like any other.
-In fact, these JAXB-annotated view models are in many regards the most powerful of all the various ways of writing view models:
-
-* their entire state (collections as well as properties) is automatically managed from interaction to interaction. +
-+
-In contrast, using xref:../rgant/rgant.adoc#_rgant-ViewModel[`@ViewModel`] (or its xref:../rgant/rgant.adoc#_rgant-DomainObject_nature[`@DomainObject#nature()`] equivalent) will only manage the state of properties, but not collections.
-And if using the xref:../rgcms/rgcms.adoc#_rgcms_classes_super_ViewModel[`ViewModel`] interface, then the programmer must write all the state management (lots of boilerplate).
-
-* JAXB-annotated view models are "in effect" editable.
-
-The examples in this section uses the DTO for `ToDoItem`, taken from the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp].
-This DTO is defined as follows:
-
-[source,java]
-----
-package todoapp.app.viewmodels.todoitem.v1;                         // <1>
-@XmlRootElement(name = "toDoItemDto")                               // <2>
-@XmlType(
-        propOrder = {                                               // <3>
-            "majorVersion", "minorVersion",
-            "description", "category", ...
-            "toDoItem", "similarItems"
-        }
-)
-@DomainObjectLayout(
-        titleUiEvent = TitleUiEvent.Doop.class                      // <4>
-)
-public class ToDoItemV1_1 implements Dto {                          // <5>
-    @XmlElement(required = true, defaultValue = "1")                // <6>
-    public final String getMajorVersion() { return "1"; }
-    @XmlElement(required = true, defaultValue = "1")                // <7>
-    public String getMinorVersion() { return "1"; }
-
-    @XmlElement(required = true)                                    // <8>
-    @Getter @Setter
-    protected String description;
-    @XmlElement(required = true)
-    @Getter @Setter
-    protected String category;
-    ...
-
-    @Getter @Setter                                                 // <9>
-    protected ToDoItem toDoItem;
-    @XmlElementWrapper                                              // <10>
-    @XmlElement(name = "todoItem")
-    @Getter @Setter
-    protected List<ToDoItem> similarItems = Lists.newArrayList();
-}
-----
-<1> package name encodes major version; see discussion on xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_versioning[versioning]
-<2> identifies this class as a view model and defines the root element for JAXB serialization
-<3> all properties in the class must be listed; (they can be ignored using `@XmlTransient`)
-<4> demonstrating use of UI events for a subscriber to provide the DTO's title; see xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_titleUiEvent[`@DomainObjectLayout#titleUiEvent()`].
-<5> class name encodes (major and) minor version; see discussion on xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_versioning[versioning]
-<6> again, see discussion on xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_versioning[versioning]
-<7> again, see discussion on xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_versioning[versioning]
-<8> simple scalar properties
-<9> reference to a persistent entity; discussed xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_referencing-domain-entities[below]
-<10> reference to a collection of persistent entities; again discussed xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_referencing-domain-entities[below]
-
-
-
-[[__ugbtb_view-models_jaxb_referencing-domain-entities]]
-=== Referencing Domain Entities
-
-It's quite common for view models to be "backed by" (be projections of) some underlying domain entity.
-The `ToDoItemDto` we've been using as the example in this section is an example: there is an underlying `ToDoItem` entity.
-
-It wouldn't make sense to serialize out the state of a persistent entity: the point of a DTO is to act as a facade on top of the entity so that the implementation details (of the entity's structure) don't leak out to the consumer.
-However, the identity of the underlying entity can be well defined; Apache Isis defines the xref:../rgcms/rgcms.adoc#_rgcms_schema-common[Common schema] which defines the `<oid-dto>` element (and corresponding `OidDto` class): the object's type and its identifier.
-This is basically a formal XML equivalent to the `Bookmark` object obtained from the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`].
-
-There is only one requirement to make this work: every referenced domain entity must be annotated with xref:../rgant/rgant.adoc#_rgant-XmlJavaTypeAdapter[`@XmlJavaTypeAdapter`], specifying the framework-provided `PersistentEntityAdapter.class`.
-This class is similar to the `BookmarkService`: it knows how to create an `OidDto` from an object reference.
-
-Thus, in our view model we can legitimately write:
-
-[source,java]
-----
-package todoapp.app.viewmodels.todoitem.v1;
-...
-public class ToDoItemV1_1 implements Dto {
-    ...
-    @Getter @Setter
-    protected ToDoItem toDoItem;
-}
-----
-
-All we need to do is remember to add that `@XmlJavaTypeAdapter` annotation to the referenced entity:
-
-[source,java]
-----
-@XmlJavaTypeAdapter(PersistentEntityAdapter.class)
-public class ToDoItem ...  {
-    ...
-}
-----
-
-
-It's also possible for a DTO to hold collections of objects.
-These can be of any type, either simple properties, or references to other objects.
-The only bit of boilerplate that is required is the `@XmlElementWrapper` annotation.
-This instructs JAXB to create an XML element (based on the field name) to contain each of the elements.
-(If this is omitted then the contents of the collection are at the same level as the properties; almost certainly not what is required).
-
-For example, the DTO also contains:
-
-[source,java]
-----
-package todoapp.app.viewmodels.todoitem.v1;
-...
-public class ToDoItemV1_1 implements Dto {
-    ...
-    @XmlElementWrapper
-    @XmlElement(name = "todoItem")
-    @Getter @Setter
-    protected List<ToDoItem> similarItems = Lists.newArrayList();
-}
-----
-
-
-There's nothing to prevent a JAXB DTO from containing rich graphs of data, parent containing children containing children.
-Be aware though that all of this state will become the DTO's memento, ultimately converted into a URL-safe form, by way of the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UrlEncodingService[`UrlEncodingService`].
-
-There are limits to the lengths of URLs, however.
-Therefore the DTO should not include state that can easily be derived from other information.
-If the URL does exceed limits, then provide a custom implementation of xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UrlEncodingService[`UrlEncodingService`] to handle the memento string in some other fashion (eg substituting it with a GUID, with the memento cached somehow on the server).
-
-
-
-
-
-[[__ugbtb_view-models_jaxb_versioning]]
-=== Versioning
-
-The whole point of using DTOs (in Apache Isis, at least) is to define a formal contact between two inter-operating but independent applications.
-Since the only thing we can predicate about the future with any certainty is that it one or both of these applications will change, we should version DTOs from the get-go.
-This allows us to make changes going forward without unnecessarily breaking existing consumers of the data.
-
-[NOTE]
-====
-There are several ways that versioning might be accomplished; we base our guidelines on this link:http://www.xfront.com/Versioning.pdf[article] taken from Roger Costello's blog, well worth a read.
-====
-
-We can distinguish two types of changes:
-
-* backwardly compatible changes
-* breaking changes.
-
-We can immediately say that the XSD namespace should change only when there is a major/breaking change, if following link:http://semver.org[semantic versioning] that means when we bump the major version number v1, v2, etc.
-
-XML namespaces correspond (when using JAXB) to Java packages.
-We should therefore place our DTOs in a package that contains only the major number; this package will eventually contain a range of DTOs that are intended to be backwardly compatible with one another.
-The package should also have a `package-info.java`; it is this that declares the XSD namespace:
-
-[source,java]
-----
-@javax.xml.bind.annotation.XmlSchema(
-        namespace = "http://viewmodels.app.todoapp/todoitem/v1/Dto.xsd",        // <1>
-        xmlns = {
-                @javax.xml.bind.annotation.XmlNs(
-                        namespaceURI = "http://isis.apache.org/schema/common",
-                        prefix = "com"
-                )
-        },
-        elementFormDefault = javax.xml.bind.annotation.XmlNsForm.QUALIFIED
-)
-package todoapp.app.viewmodels.todoitem.v1;                                     // <2>
-----
-<1> the namespace URI, used by the DTO residing in this package.
-<2> the package in which the DTO resides.  Note that this contains only the major version.
-
-Although there is no requirement for the namespace URI to correspond to a physical URL, it should be unique.
-This usually means including a company domain name within the string.
-
-As noted above, this package will contain multiple DTO classes all with the same namespace; these represent a set of minor versions of the DTO, each subsequent one intended to be backwardly compatible with the previous.
-Since these DTO classes will all be in the same package (as per the xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_using-packages-to-version[advice above]), the class should therefore include the minor version name:
-
-[source,java]
-----
-package todoapp.app.viewmodels.todoitem.v1;     // <1>
-...
-public class ToDoItemV1_1 implements Dto {      // <2>
-    ...
-}
-----
-<1> package contains the major version only
-<2> DTO class contains the (major and) minor version
-
-
-We also recommend that each DTO instance should also specify the version of the XSD schema that it is logically compatible with.
-Probably most consumers will not persist the DTOs; they will be processed and then discarded.
-However, it would be wrong to assume that is the case in all cases; some consumers might choose to persist the DTO (eg for replay at some later state).
-
-Thus:
-
-[source,java]
-----
-public class ToDoItemV1_1 implements Dto {
-    @XmlElement(required = true, defaultValue = "1")
-    public final String getMajorVersion() { return "1"; }   // <1>
-    @XmlElement(required = true, defaultValue = "1")
-    public String getMinorVersion() { return "1"; }         // <2>
-    ...
-}
-----
-<1> returns the major version (in sync with the package)
-<2> returns the minor version (in sync with the class name)
-
-These methods always return a hard-coded literal.
-Any instances serialized from these classes will implicitly "declare" the (major and) minor version of the schema with which they are compatible.
-If a consumer has a minimum version that it requires, it can therefore inspect the XML instance itself to determine if it is able to consume said XML.
-
-If a new (minor) version of a DTO is required, then we recommend copying-and-pasting the previous version, eg:
-
-[source,java]
-----
-public class ToDoItemV1_2 implements Dto {
-    @XmlElement(required = true, defaultValue = "1")
-    public final String getMajorVersion() { return "1"; }
-    @XmlElement(required = true, defaultValue = "2")
-    public String getMinorVersion() { return "2"; }
-    ...
-}
-----
-
-Obviously, only changes made must be backward compatible, eg new members must be optional.
-
-Alternatively, you might also consider simply editing the source file, ie renaming the class and bumping up the value returned by `getMinorVersion()`.
-
-We also _don't_ recommend using inheritance (ie `ToDoItemV1_2` should not inherit from `ToDoItemV1_1`; this creates unnecessary complexity downstream if generating XSDs and DTOs for the downstream consumer.
-
-
-[[__ugbtb_view-models_jaxb_generating-xsds-and-dtos]]
-=== Generating XSDs and DTOs
-
-In the section xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_referencing-domain-entities[above] it was explained how a view model DTO can transparent reference any "backing" entities; these references are converted to internal object identifiers.
-
-However, if the consumer of the XML is another Java process (eg running within an Apache Camel route), then you might be tempted/expect to be able to use the same DTO within that Java process.
-After a little thought though you'll realize that (duh!) of course you cannot; the consumer runs in a different process space, and will not have references to those containing entities.
-
-There are therefore two options:
-
-* either choose not to have the view model DTO reference any persistent entities, and simply limit the DTO to simple scalars. +
-+
-Such a DTO will then be usable in both the Apache Isis app (to generate the original XML) and in the consumer.
-The xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`] can be used to obtain the object identifiers
-
-* alternatively, generate a different DTO for the consumer from the XSD of the view model DTO.
-
-The (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] uses the second approach; generating the XSD and consumer's DTO is mostly just boilerplate `pom.xml` file.
-In the todoapp this can be found in the `todoapp-xsd` Maven module, whose `pom.xml` is structured as two profiles:
-
-[source,xml]
-----
-<project ... >
-    <artifactId>todoapp-xsd</artifactId>
-    <dependencies>
-        <dependency>
-            <groupId>${project.groupId}</groupId>
-            <artifactId>todoapp-app</artifactId>
-        </dependency>
-    </dependencies>
-    <profiles>
-        <profile>
-            <id>isis-xsd</id>
-            <activation>
-                <property>
-                    <name>!skip.isis-xsd</name>
-                </property>
-            </activation>
-            ...
-        </profile>
-        <profile>
-            <id>xjc</id>
-            <activation>
-                <property>
-                    <name>!skip.xjc</name>
-                </property>
-            </activation>
-            ...
-        </profile>
-    </profiles>
-</project>
-----
-
-The `isis-xsd` profile generates the XSD using the xref:../rgmvn/rgmvn.adoc#_rgmvn_xsd[`xsd` goal] of Isis' maven plugin:
-
-[source,xml]
-----
-<build>
-    <plugins>
-        <plugin>
-            <groupId>org.apache.isis.tool</groupId>
-            <artifactId>isis-maven-plugin</artifactId>
-            <version>${isis.version}</version>
-            <configuration>
-                <appManifest>todoapp.dom.ToDoAppDomManifest</appManifest>
-                <jaxbClasses>
-                    <jaxbClass>todoapp.app.viewmodels.todoitem.v1.ToDoItemV1_1</jaxbClass>
-                </jaxbClasses>
-                <separate>false</separate>
-                <commonSchemas>false</commonSchemas>
-            </configuration>
-            <dependencies>
-                <dependency>
-                    <groupId>${project.groupId}</groupId>
-                    <artifactId>todoapp-dom</artifactId>
-                    <version>${project.version}</version>
-                </dependency>
-                <dependency>
-                    <groupId>com.google.guava</groupId>
-                    <artifactId>guava</artifactId>
-                    <version>16.0.1</version>
-                </dependency>
-            </dependencies>
-            <executions>
-                <execution>
-                    <phase>generate-sources</phase>
-                    <goals>
-                        <goal>xsd</goal>
-                    </goals>
-                </execution>
-            </executions>
-        </plugin>
-        <plugin>
-            <artifactId>maven-assembly-plugin</artifactId>
-            <version>2.5.3</version>
-            <configuration>
-                <descriptor>src/assembly/dep.xml</descriptor>
-            </configuration>
-            <executions>
-                <execution>
-                    <id>create-archive</id>
-                    <phase>package</phase>
-                    <goals>
-                        <goal>single</goal>
-                    </goals>
-                </execution>
-            </executions>
-        </plugin>
-    </plugins>
-</build>
-----
-
-The `todoapp.dom.ToDoAppDomManifest` is a cut-down version of the app manifest that identifies only the `dom` domain services.
-
-The `xjc` profile, meanwhile, uses the `maven-jaxb2-plugin` (a wrapper around the `schemagen` JDK tool) to generate a DTO from the XSD generated by the preceding profile:
-
-[source,xml]
-----
-<build>
-    <plugins>
-        <plugin>
-            <groupId>org.jvnet.jaxb2.maven2</groupId>
-            <artifactId>maven-jaxb2-plugin</artifactId>
-            <version>0.12.3</version>
-            <executions>
-                <execution>
-                    <id>xjc-generate</id>
-                    <phase>generate-sources</phase>
-                    <goals>
-                        <goal>generate</goal>
-                    </goals>
-                </execution>
-            </executions>
-            <configuration>
-                <removeOldOutput>true</removeOldOutput>
-                <schemaDirectory>
-                    target/generated-resources/isis-xsd/viewmodels.app.todoapp
-                </schemaDirectory>
-                <schemaIncludes>
-                    <schemaInclude>todoitem/v1/Dto.xsd</schemaInclude>
-                </schemaIncludes>
-                <bindingDirectory>src/main/resources</bindingDirectory>
-                <bindingIncludes>
-                    <bindingInclude>binding.xml</bindingInclude>
-                </bindingIncludes>
-                <catalog>src/main/resources/catalog.xml</catalog>
-            </configuration>
-        </plugin>
-        <plugin>
-            <groupId>org.codehaus.mojo</groupId>
-            <artifactId>build-helper-maven-plugin</artifactId>
-            <version>1.9.1</version>
-            <executions>
-                <execution>
-                    <id>add-source</id>
-                    <phase>generate-sources</phase>
-                    <goals>
-                        <goal>add-source</goal>
-                    </goals>
-                    <configuration>
-                    <sources>
-                        <source>target/generated-sources/xjc</source>
-                    </sources>
-                    </configuration>
-                </execution>
-            </executions>
-        </plugin>
-    </plugins>
-</build>
-----
-
-
-''''
-''''
-
-== (Non-JAXB) View Models
-
-NOTE: FIXME - consider this as deprecated
-
-This section describes how to implement view models.
-
-Fundamentally all view models' state is serialized into
-a string memento; this memento is then held by the client (browser) in the form of a URL.  As you might imagine, this
-URL can become quite long, but Apache Isis offers a mechanism (the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UrlEncodingService[`UrlEncodingService`]) if it exceeds the maximum length for a URL
-(2083 characters).  Also, of course, this string memento must only contain characters that it is valid for use within
-a URL.
-
-While the underlying technique is the same irrespective of use case, the programming model provides various ways of
-defining a view model so that the original intent is not lost.  They are:
-
-.View model programming model
-[cols="1a,4a,2a", options="header"]
-|===
-
-| Use case
-| Code
-| Description
-
-
-| External entity
-|[source,java]
-----
-@DomainObject(nature=Nature.EXTERNAL_ENTITY)
-public class CustomerRecordOnSAP { ... }
-----
-|Annotated with xref:../rgant/rgant.adoc#_rgant-DomainObject_nature[`@DomainObject#nature()`] and a nature of `EXTERNAL_ENTITY`, with memento derived automatically from the properties of the domain object.  Collections are ignored, as are any properties annotated as xref:../rgant/rgant.adoc#_rgant-Property_notPersisted[not persisted].
-
-| In-memory entity
-|[source,java]
-----
-@DomainObject(nature=Nature.INMEMORY_ENTITY)
-public class Log4JAppender { ... }
-----
-|As preceding, but using a nature of `INMEMORY_ENTITY`.
-
-|Application view model
-|[source,java]
-----
-@DomainObject(nature=Nature.VIEW_MODEL)
-public class Dashboard { ... }
-----
-|As preceding, but using a nature of `VIEW_MODEL`.
-
-|Application view model
-|
-[source,java]
-----
-@ViewModel
-public class Dashboard { ... }
-----
-
-|Annotated with xref:../rgant/rgant.adoc#_rgant-ViewModel[`@ViewModel`] annotation (effectively just an alias)' memento is as preceding: from "persisted" properties, collections ignored
-
-|Application view model
-|
-[source,java]
-----
-public class ExcelUploadManager implements ViewModel {
-  public String viewModelMemento() { ... }
-  public void viewModelInit(String memento) { ... }
-}
-|Implement xref:../rgcms/rgcms.adoc#_rgcms_classes_super_ViewModel[`ViewModel`] interface.  The memento is as defined by the
-interface's methods: the programmer has full control (but also full responsibility) for the string memento.
-
-|DTO
-|
-[source,java]
-----
-@XmlRootElement("customer")
-public class CustomerDto { ... }
-----
-|Annotate using JAXB xref:../rgant/rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`] annotation.  Memento
-derived automatically by serializing the XML graph as implied by the JAXB annotations.  Note that (unlike `@ViewModel`
-et al) this state _can_ include collections.
-|===
-
-JAXB-annotated DTOs are discussed in more detail immediately xref:rg.adoc#_ugbtb_view-models_jaxb[below].
-
-
-
-''''
-''''
-
-
-
-This section describes how to implement view models.
-
-Fundamentally all view models' state is serialized into
-a string memento; this memento is then held by the client (browser) in the form of a URL.  As you might imagine, this
-URL can become quite long, but Apache Isis offers a mechanism (the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UrlEncodingService[`UrlEncodingService`]) if it exceeds the maximum length for a URL
-(2083 characters).  Also, of course, this string memento must only contain characters that it is valid for use within
-a URL.
-
-While the underlying technique is the same irrespective of use case, the programming model provides various ways of
-defining a view model so that the original intent is not lost.  They are:
-
-.View model programming model
-[cols="1a,4a,2a", options="header"]
-|===
-
-| Use case
-| Code
-| Description
-
-
-| External entity
-|[source,java]
-----
-@DomainObject(nature=Nature.EXTERNAL_ENTITY)
-public class CustomerRecordOnSAP { ... }
-----
-|Annotated with xref:../rgant/rgant.adoc#_rgant-DomainObject_nature[`@DomainObject#nature()`] and a nature of `EXTERNAL_ENTITY`, with memento derived automatically from the properties of the domain object.  Collections are ignored, as are any properties annotated as xref:../rgant/rgant.adoc#_rgant-Property_notPersisted[not persisted].
-
-| In-memory entity
-|[source,java]
-----
-@DomainObject(nature=Nature.INMEMORY_ENTITY)
-public class Log4JAppender { ... }
-----
-|As preceding, but using a nature of `INMEMORY_ENTITY`.
-
-|Application view model
-|[source,java]
-----
-@DomainObject(nature=Nature.VIEW_MODEL)
-public class Dashboard { ... }
-----
-|As preceding, but using a nature of `VIEW_MODEL`.
-
-|Application view model
-|
-[source,java]
-----
-@ViewModel
-public class Dashboard { ... }
-----
-
-|Annotated with xref:../rgant/rgant.adoc#_rgant-ViewModel[`@ViewModel`] annotation (effectively just an alias)' memento is as preceding: from "persisted" properties, collections ignored
+* The more powerful/flexible approach is to use JAXB annotations; this allows the state of the object's properties and also its collections.
 
-|Application view model
-|
-[source,java]
-----
-public class ExcelUploadManager implements ViewModel {
-  public String viewModelMemento() { ... }
-  public void viewModelInit(String memento) { ... }
-}
-|Implement xref:../rgcms/rgcms.adoc#_rgcms_classes_super_ViewModel[`ViewModel`] interface.  The memento is as defined by the
-interface's methods: the programmer has full control (but also full responsibility) for the string memento.
+* The other approach is to use Apache Isis specific annotations.
+While (arguably) these explain the intent of the view model better, they are more restrictive: only the state of the object's properties is serialized -- collections are ignored -- and not every datatype is recognized.
 
-|DTO
-|
-[source,java]
-----
-@XmlRootElement("customer")
-public class CustomerDto { ... }
-----
-|Annotate using JAXB xref:../rgant/rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`] annotation.  Memento
-derived automatically by serializing the XML graph as implied by the JAXB annotations.  Note that (unlike `@ViewModel`
-et al) this state _can_ include collections.
-|===
+The serialized form of these view models is therefore XML, which also enables these view models to act as DTO (useful for various integration scenarios).
 
-JAXB-annotated DTOs are discussed in more detail immediately xref:rg.adoc#_ugbtb_view-models_jaxb[below].
+For these reasons we recommend that you use JAXB-style view models wherever possible.
+Indeed, the legacy approach for view models may be deprecated in the future.
 
+In the sections below we consider JAXB view models both as "regular" view models, and also when using them to act as DTOs.
 
 
+include::_ugfun_programming-model_view-models_jaxb.adoc[leveloffset=+1]
+include::_ugfun_programming-model_view-models_dto.adoc[leveloffset=+1]
+include::_ugfun_programming-model_view-models_non-jaxb.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_dto.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_dto.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_dto.adoc
new file mode 100644
index 0000000..ad5b8fd
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_dto.adoc
@@ -0,0 +1,69 @@
+[[_ugfun_programming-model_view-models_dto]]
+= DTOs
+
+: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/
+
+
+JAXB view models can also be used as DTOs.
+The examples in this section uses the DTO for `ToDoItem`, taken from the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp].
+
+This DTO is defined as follows:
+
+[source,java]
+----
+package todoapp.app.viewmodels.todoitem.v1;                         // <1>
+@XmlRootElement(name = "toDoItemDto")                               // <2>
+@XmlType(
+        propOrder = {                                               // <3>
+            "majorVersion", "minorVersion",
+            "description", "category", ...
+            "toDoItem", "similarItems"
+        }
+)
+@DomainObjectLayout(
+        titleUiEvent = TitleUiEvent.Doop.class                      // <4>
+)
+public class ToDoItemV1_1 implements Dto {                          // <5>
+    @XmlElement(required = true, defaultValue = "1")                // <6>
+    public final String getMajorVersion() { return "1"; }
+    @XmlElement(required = true, defaultValue = "1")                // <7>
+    public String getMinorVersion() { return "1"; }
+
+    @XmlElement(required = true)                                    // <8>
+    @Getter @Setter
+    protected String description;
+    @XmlElement(required = true)
+    @Getter @Setter
+    protected String category;
+    ...
+
+    @Getter @Setter                                                 // <9>
+    protected ToDoItem toDoItem;
+    @XmlElementWrapper                                              // <10>
+    @XmlElement(name = "todoItem")
+    @Getter @Setter
+    protected List<ToDoItem> similarItems = Lists.newArrayList();
+}
+----
+<1> package name encodes major version; see discussion on xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_versioning[versioning]
+<2> identifies this class as a view model and defines the root element for JAXB serialization
+<3> all properties in the class must be listed; (they can be ignored using `@XmlTransient`)
+<4> demonstrating use of UI events for a subscriber to provide the DTO's title; see xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_titleUiEvent[`@DomainObjectLayout#titleUiEvent()`].
+<5> class name encodes (major and) minor version; see discussion on xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_versioning[versioning]
+<6> again, see discussion on xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_versioning[versioning]
+<7> again, see discussion on xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_versioning[versioning]
+<8> simple scalar properties
+<9> reference to a persistent entity; discussed xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_referencing-domain-entities[below]
+<10> reference to a collection of persistent entities; again discussed xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_referencing-domain-entities[below]
+
+
+
+
+
+include::_ugfun_programming-model_view-models_dto_versioning.adoc[leveloffset=+1]
+
+include::_ugfun_programming-model_view-models_dto_generating-xsds.adoc[leveloffset=+1]
+
+include::_ugfun_programming-model_view-models_dto_dto-consumers.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_dto_dto-consumers.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_dto_dto-consumers.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_dto_dto-consumers.adoc
new file mode 100644
index 0000000..5d1e22d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_dto_dto-consumers.adoc
@@ -0,0 +1,32 @@
+[[_ugfun_programming-model_view-models_dto_dto-consumers.adoc]]
+= DTO Consumers
+: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/
+
+
+
+The actual consumers of DTOs will generally obtain the XML of the view models either by requesting the XML directly, eg using the xref:../ugvro/ugvro.adoc#[RestfulObjects viewer], or may have the XML sent to them asynchronously using an ESB such as Apache Camel.
+
+In the former case, the consumer requests the DTO by calling the REST API with the appropriate HTTP `Accept` header.
+An appropriate implementation of xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`] can then be used to return the appropriate DTO (as XML).
+
+For the latter case, one design is simply for the application to instantiate the view model, then call the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_JaxbService[`JaxbService`] to obtain its corresponding XML.  This can then be published onto the ESB, for example using an http://activemq.apache.org[Apache ActiveMQ (TM)] queue.
+
+However, rather than try to push all the data that might be needed by any of these external systems in a single XML event (which would require anticipating all the requirements, likely a hopeless task), a better design is to publish only the fact that something of note has changed - ie, that an action on a domain object has been invoked - and then let the consumers call back to obtain other information if required.
+This can once again be done by calling the REST API with an appropriate HTTP `Accept` header.
+
+[TIP]
+====
+This is an example of the link:https://leanpub.com/camel-design-patterns[VETRO pattern] (validate, enrich, transform, route, operate).
+In our case we focus on the validation (to determine the nature of the inbound message, ie which action was invoked), and the enrich (callback to obtain a DTO with additional information required by the consumer).
+====
+
+The (non-ASF) http://github.com/isisaddons/isis-module-publishmq[Isis addons' publishmq] module provides an out-of-the-box solution of this design.
+It provides an implementation of the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`], but which simply publishes instances of xref:../rgcms/rgcms.adoc#_rgcms_schema-aim[`ActionInvocationMemento`] to an ActiveMQ queue.
+Camel (or similar) can then be hooked up to consume these events from this queue, and use a processor to parse the action memento to determine what has changed on the source system.
+Thereafter, a subsequent Camel processor can then call back to the source - via the xref:../ugvro/ugvro.adoc#[Restful Objects viewer] - to enrich the message with additional details using a DTO.
+
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_dto_generating-xsds.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_dto_generating-xsds.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_dto_generating-xsds.adoc
new file mode 100644
index 0000000..e040f43
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_dto_generating-xsds.adoc
@@ -0,0 +1,176 @@
+[[_ugfun_programming-model_view-models_dto_generating-xsds]]
+= Generating XSDs and DTOs
+: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/
+
+
+
+
+In the section xref:../ugfun/ugfun.adoc#_ugfun_programming-model_view-models_jaxb_referencing-domain-entities[above] it was explained how a view model DTO can transparent reference any "backing" entities; these references are converted to internal object identifiers.
+
+However, if the consumer of the XML is another Java process (eg running within an Apache Camel route), then you might be tempted/expect to be able to use the same DTO within that Java process.
+After a little thought though you'll realize that (duh!) of course you cannot; the consumer runs in a different process space, and will not have references to those containing entities.
+
+There are therefore two options:
+
+* either choose not to have the view model DTO reference any persistent entities, and simply limit the DTO to simple scalars. +
++
+Such a DTO will then be usable in both the Apache Isis app (to generate the original XML) and in the consumer.
+The xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`] can be used to obtain the object identifiers
+
+* alternatively, generate a different DTO for the consumer from the XSD of the view model DTO.
+
+The (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] uses the second approach; generating the XSD and consumer's DTO is mostly just boilerplate `pom.xml` file.
+In the todoapp this can be found in the `todoapp-xsd` Maven module, whose `pom.xml` is structured as two profiles:
+
+[source,xml]
+----
+<project ... >
+    <artifactId>todoapp-xsd</artifactId>
+    <dependencies>
+        <dependency>
+            <groupId>${project.groupId}</groupId>
+            <artifactId>todoapp-app</artifactId>
+        </dependency>
+    </dependencies>
+    <profiles>
+        <profile>
+            <id>isis-xsd</id>
+            <activation>
+                <property>
+                    <name>!skip.isis-xsd</name>
+                </property>
+            </activation>
+            ...
+        </profile>
+        <profile>
+            <id>xjc</id>
+            <activation>
+                <property>
+                    <name>!skip.xjc</name>
+                </property>
+            </activation>
+            ...
+        </profile>
+    </profiles>
+</project>
+----
+
+The `isis-xsd` profile generates the XSD using the xref:../rgmvn/rgmvn.adoc#_rgmvn_xsd[`xsd` goal] of Isis' maven plugin:
+
+[source,xml]
+----
+<build>
+    <plugins>
+        <plugin>
+            <groupId>org.apache.isis.tool</groupId>
+            <artifactId>isis-maven-plugin</artifactId>
+            <version>${isis.version}</version>
+            <configuration>
+                <appManifest>todoapp.dom.ToDoAppDomManifest</appManifest>
+                <jaxbClasses>
+                    <jaxbClass>todoapp.app.viewmodels.todoitem.v1.ToDoItemV1_1</jaxbClass>
+                </jaxbClasses>
+                <separate>false</separate>
+                <commonSchemas>false</commonSchemas>
+            </configuration>
+            <dependencies>
+                <dependency>
+                    <groupId>${project.groupId}</groupId>
+                    <artifactId>todoapp-dom</artifactId>
+                    <version>${project.version}</version>
+                </dependency>
+                <dependency>
+                    <groupId>com.google.guava</groupId>
+                    <artifactId>guava</artifactId>
+                    <version>16.0.1</version>
+                </dependency>
+            </dependencies>
+            <executions>
+                <execution>
+                    <phase>generate-sources</phase>
+                    <goals>
+                        <goal>xsd</goal>
+                    </goals>
+                </execution>
+            </executions>
+        </plugin>
+        <plugin>
+            <artifactId>maven-assembly-plugin</artifactId>
+            <version>2.5.3</version>
+            <configuration>
+                <descriptor>src/assembly/dep.xml</descriptor>
+            </configuration>
+            <executions>
+                <execution>
+                    <id>create-archive</id>
+                    <phase>package</phase>
+                    <goals>
+                        <goal>single</goal>
+                    </goals>
+                </execution>
+            </executions>
+        </plugin>
+    </plugins>
+</build>
+----
+
+The `todoapp.dom.ToDoAppDomManifest` is a cut-down version of the app manifest that identifies only the `dom` domain services.
+
+The `xjc` profile, meanwhile, uses the `maven-jaxb2-plugin` (a wrapper around the `schemagen` JDK tool) to generate a DTO from the XSD generated by the preceding profile:
+
+[source,xml]
+----
+<build>
+    <plugins>
+        <plugin>
+            <groupId>org.jvnet.jaxb2.maven2</groupId>
+            <artifactId>maven-jaxb2-plugin</artifactId>
+            <version>0.12.3</version>
+            <executions>
+                <execution>
+                    <id>xjc-generate</id>
+                    <phase>generate-sources</phase>
+                    <goals>
+                        <goal>generate</goal>
+                    </goals>
+                </execution>
+            </executions>
+            <configuration>
+                <removeOldOutput>true</removeOldOutput>
+                <schemaDirectory>
+                    target/generated-resources/isis-xsd/viewmodels.app.todoapp
+                </schemaDirectory>
+                <schemaIncludes>
+                    <schemaInclude>todoitem/v1/Dto.xsd</schemaInclude>
+                </schemaIncludes>
+                <bindingDirectory>src/main/resources</bindingDirectory>
+                <bindingIncludes>
+                    <bindingInclude>binding.xml</bindingInclude>
+                </bindingIncludes>
+                <catalog>src/main/resources/catalog.xml</catalog>
+            </configuration>
+        </plugin>
+        <plugin>
+            <groupId>org.codehaus.mojo</groupId>
+            <artifactId>build-helper-maven-plugin</artifactId>
+            <version>1.9.1</version>
+            <executions>
+                <execution>
+                    <id>add-source</id>
+                    <phase>generate-sources</phase>
+                    <goals>
+                        <goal>add-source</goal>
+                    </goals>
+                    <configuration>
+                    <sources>
+                        <source>target/generated-sources/xjc</source>
+                    </sources>
+                    </configuration>
+                </execution>
+            </executions>
+        </plugin>
+    </plugins>
+</build>
+----

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_dto_versioning.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_dto_versioning.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_dto_versioning.adoc
new file mode 100644
index 0000000..2c61f4e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_dto_versioning.adoc
@@ -0,0 +1,106 @@
+[[_ugfun_programming-model_view-models_dto_versioning]]
+= Versioning
+
+: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/
+
+
+The whole point of using DTOs (in Apache Isis, at least) is to define a formal contact between two inter-operating but independent applications.
+Since the only thing we can predicate about the future with any certainty is that it one or both of these applications will change, we should version DTOs from the get-go.
+This allows us to make changes going forward without unnecessarily breaking existing consumers of the data.
+
+[NOTE]
+====
+There are several ways that versioning might be accomplished; we base our guidelines on this link:http://www.xfront.com/Versioning.pdf[article] taken from Roger Costello's blog, well worth a read.
+====
+
+We can distinguish two types of changes:
+
+* backwardly compatible changes
+* breaking changes.
+
+We can immediately say that the XSD namespace should change only when there is a major/breaking change, if following link:http://semver.org[semantic versioning] that means when we bump the major version number v1, v2, etc.
+
+XML namespaces correspond (when using JAXB) to Java packages.
+We should therefore place our DTOs in a package that contains only the major number; this package will eventually contain a range of DTOs that are intended to be backwardly compatible with one another.
+The package should also have a `package-info.java`; it is this that declares the XSD namespace:
+
+[source,java]
+----
+@javax.xml.bind.annotation.XmlSchema(
+        namespace = "http://viewmodels.app.todoapp/todoitem/v1/Dto.xsd",        // <1>
+        xmlns = {
+                @javax.xml.bind.annotation.XmlNs(
+                        namespaceURI = "http://isis.apache.org/schema/common",
+                        prefix = "com"
+                )
+        },
+        elementFormDefault = javax.xml.bind.annotation.XmlNsForm.QUALIFIED
+)
+package todoapp.app.viewmodels.todoitem.v1;                                     // <2>
+----
+<1> the namespace URI, used by the DTO residing in this package.
+<2> the package in which the DTO resides.  Note that this contains only the major version.
+
+Although there is no requirement for the namespace URI to correspond to a physical URL, it should be unique.
+This usually means including a company domain name within the string.
+
+As noted above, this package will contain multiple DTO classes all with the same namespace; these represent a set of minor versions of the DTO, each subsequent one intended to be backwardly compatible with the previous.
+Since these DTO classes will all be in the same package (as per the xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_using-packages-to-version[advice above]), the class should therefore include the minor version name:
+
+[source,java]
+----
+package todoapp.app.viewmodels.todoitem.v1;     // <1>
+...
+public class ToDoItemV1_1 implements Dto {      // <2>
+    ...
+}
+----
+<1> package contains the major version only
+<2> DTO class contains the (major and) minor version
+
+
+We also recommend that each DTO instance should also specify the version of the XSD schema that it is logically compatible with.
+Probably most consumers will not persist the DTOs; they will be processed and then discarded.
+However, it would be wrong to assume that is the case in all cases; some consumers might choose to persist the DTO (eg for replay at some later state).
+
+Thus:
+
+[source,java]
+----
+public class ToDoItemV1_1 implements Dto {
+    @XmlElement(required = true, defaultValue = "1")
+    public final String getMajorVersion() { return "1"; }   // <1>
+    @XmlElement(required = true, defaultValue = "1")
+    public String getMinorVersion() { return "1"; }         // <2>
+    ...
+}
+----
+<1> returns the major version (in sync with the package)
+<2> returns the minor version (in sync with the class name)
+
+These methods always return a hard-coded literal.
+Any instances serialized from these classes will implicitly "declare" the (major and) minor version of the schema with which they are compatible.
+If a consumer has a minimum version that it requires, it can therefore inspect the XML instance itself to determine if it is able to consume said XML.
+
+If a new (minor) version of a DTO is required, then we recommend copying-and-pasting the previous version, eg:
+
+[source,java]
+----
+public class ToDoItemV1_2 implements Dto {
+    @XmlElement(required = true, defaultValue = "1")
+    public final String getMajorVersion() { return "1"; }
+    @XmlElement(required = true, defaultValue = "2")
+    public String getMinorVersion() { return "2"; }
+    ...
+}
+----
+
+Obviously, only changes made must be backward compatible, eg new members must be optional.
+
+Alternatively, you might also consider simply editing the source file, ie renaming the class and bumping up the value returned by `getMinorVersion()`.
+
+We also _don't_ recommend using inheritance (ie `ToDoItemV1_2` should not inherit from `ToDoItemV1_1`; this creates unnecessary complexity downstream if generating XSDs and DTOs for the downstream consumer.
+
+

[38/58] [abbrv] isis git commit: ugfun.adoc - services and mixins

[da...@apache.org]

ugfun.adoc - services and mixins


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/9e1ea1b6
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/9e1ea1b6
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/9e1ea1b6

Branch: refs/heads/wip
Commit: 9e1ea1b605d58db4524b6d35a0f8bd6f9b9672e5
Parents: 9fbf3d5
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Sat Apr 15 11:04:39 2017 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Thu Apr 20 09:09:30 2017 +0100

----------------------------------------------------------------------
 .../ugfun/_ugfun_core-concepts_add-ons.adoc     |  42 ++++++++++++------
 .../ugfun/_ugfun_domain-class-ontology.adoc     |  14 +++---
 ...n_domain-class-ontology_domain-services.adoc |  43 +++++++++++++------
 .../_ugfun_domain-class-ontology_mixins.adoc    |   2 +
 .../hexagonal-architecture-addons.png           | Bin 0 -> 100666 bytes
 .../philosophy/hexagonal-architecture.png       | Bin 85844 -> 75942 bytes
 .../philosophy/hexagonal-architecture.pptx      | Bin 263812 -> 263049 bytes
 7 files changed, 69 insertions(+), 32 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/9e1ea1b6/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_add-ons.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_add-ons.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_add-ons.adoc
index cfae890..c13a4b2 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_add-ons.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_add-ons.adoc
@@ -1,36 +1,54 @@
 [[_ugfun_core-concepts_add-ons]]
-= Isis Add-ons
+= Isis Add-ons & Incode Catalog
 :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/
 
 
-The link:http://www.isisaddons.org[Isis Addons] website provides a number of reusable modules and other extensions for Apache Isis.
-This chapter focuses just on the modules, all of which have a name of the form `isis-module-xxx`.
+The link:http://www.isisaddons.org[Isis Addons] website provides a number of reusable modules for Apache Isis, focusing either on specific technologies or in technical cross-cutting concerns.
+Some of these modules implement SPIs defined by the framework.
+
+The link:http://catalog.incode.org[Incode Catalog] website also provides a number of reusable modules, focusing on business logic for generic subdomains.
+
+This section surveys the functionality available.
+
 
 [WARNING]
 ====
-Note that Isis Addons, although maintained by Apache Isis committers, are not part of the ASF.
+Note that Isis Addons and Incode Catalog, although maintained by Apache Isis committers, are not part of the ASF.
 ====
 
 
 
-The modules themselves fall into four broad groups:
+The modules themselves fall into a number of broader groups:
 
-* modules that provide an implementations of API defined by Apache Isis +
+* modules that provide an implementations of SPI defined by Apache Isis +
 +
-where Apache Isis has hooks to use the service if defined by provides no implementations of its own.  The http://github.com/isisaddons/isis-module-command[command], http://github.com/isisaddons/isis-module-audit[auditing], http://github.com/isisaddons/isis-module-publishing[publishing], http://github.com/isisaddons/isis-module-security[security]  and http://github.com/isisaddons/isis-module-sessionlogger[sessionlogger] modules fall into this category.  Typically the domain objects themselves wouldn't interact with these services
+where Apache Isis has hooks to use the service if defined by provides no implementations of its own. +
++
+From the link:http://www.isisaddons.org[Isis Addons] website, the http://github.com/isisaddons/isis-module-command[command], http://github.com/isisaddons/isis-module-audit[auditer], http://github.com/isisaddons/isis-module-publishmq[publisher], http://github.com/isisaddons/isis-module-security[security]  and http://github.com/isisaddons/isis-module-sessionlogger[sessionlogger] modules fall into this category.  Typically the domain objects themselves wouldn't interact with these services
 
 * modules that provide standalone domain services with their own API and implementation +
 +
-These are simply intended to be used by domain objects.  The http://github.com/isisaddons/isis-module-docx[docx], http://github.com/isisaddons/isis-module-excel[excel], http://github.com/isisaddons/isis-module-settings[settings] and http://github.com/isisaddons/isis-module-stringinterpolator[stringinterpolator] fall into this category.
+These are simply intended to be used by domain objects. +
++
+From the link:http://www.isisaddons.org[Isis Addons] website, the http://github.com/isisaddons/isis-module-docx[docx], http://github.com/isisaddons/isis-module-excel[excel], http://github.com/isisaddons/isis-module-freemarker[freemarker], http://github.com/isisaddons/isis-module-pdfbox[pdfbox], http://github.com/isisaddons/isis-module-settings[settings], http://github.com/isisaddons/isis-module-servletapi[servletapi], http://github.com/isisaddons/isis-module-stringinterpolator[stringinterpolator] and http://github.com/isisaddons/isis-module-xdocreport[xdocreport] fall into this category. +
++
+From the link:http://catalog.incode.org[Incode Catalog] website, the http://github.com/incodehq/incode-module-alias[alias], http://github.com/incodehq/incode-module-classification[classification], http://github.com/incodehq/incode-module-commchannel[commchannel], http://github.com/incodehq/incode-module-communications[communications], http://github.com/incodehq/incode-module-country[country], http://github.com/incodehq/incode-module-docfragment[docfragment],
+http://github.com/incodehq/incode-module-document[document] and http://github.com/incodehq/incode-module-document[note] modules fall into this category.
 
 * modules that provide standalone domain entities (and supporting services) for a particular subdomain +
 +
-The http://github.com/isisaddons/isis-module-tags[tags] module falls into this category
+From the link:http://www.isisaddons.org[Isis Addons] website, the http://github.com/isisaddons/isis-module-tags[tags] module falls into this category
+
+* modules that provide developer/testing utilities +
++
+From the link:http://www.isisaddons.org[Isis Addons] website, the http://github.com/isisaddons/isis-module-fakedata[fakedata] module provides fakedata for unit- and integration testing +
++
+From the link:http://catalog.incode.org[Incode Catalog] website, the http://github.com/incodehq/incode-module-fixturesupport[fixturesupport], http://github.com/incodehq/incode-module-integtestsupport[integtestsupport] and http://github.com/incodehq/incode-module-unittestsupport[unittestsupport] modules fall into this category.
 
-* modules that provide developer utilities +
+* modules that support runtime/integration support +
 +
-Not intended for use by either the framework or domain objects, but provide utilities that the developer themselves might use.  The http://github.com/isisaddons/isis-module-devutils[devutils] module (not suprisingly) falls into this category
+From the link:http://www.isisaddons.org[Isis Addons] website, link:http://github.com/isisaddons/isis-module-flywaydb[flywaydb] handle RDBMS schema migration, http://github.com/isisaddons/isis-module-quartz[quartz] provides scheduling of background jobs; and the http://github.com/isisaddons/isis-module-togglz[togglz] provides feature toggles.
 
-Each of the modules has a full README and example application demonstrating their usage.  The sections below briefly outline the capabilities of these modules.
+Each of the modules has a full README and demo application demonstrating their usage.  The sections below briefly outline the capabilities of these modules.

http://git-wip-us.apache.org/repos/asf/isis/blob/9e1ea1b6/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology.adoc
index 7e496a0..580f084 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology.adoc
@@ -6,13 +6,16 @@
 
 
 
-Apache Isis supports recognises three main types of domain classes:
+Apache Isis supports recognises four main types of domain classes:
 
-* domain entities - domain objects persisted to the database using JDO/DataNucleus; for example `Customer`
+* xref:../ugfun/ugfun.adoc#_ugfun_domain-class-ontology_domain-entities[domain entities] - domain objects persisted to the database using JDO/DataNucleus; for example `Customer`
 
-* domain services - generally singletons, automatically injected, and providing various functionality; for example `CustomerRepository`
+* xref:../ugfun/ugfun.adoc#_ugfun_domain-class-ontology_domain-services[domain services] - generally singletons, automatically injected, and providing various functionality; for example `CustomerRepository`
 
-* view models - domain objects that are a projection of some state held by the database, in support a particular use case; for example `CustomerDashboard` (to pull together commonly accessed information about a customer).
+* xref:../ugfun/ugfun.adoc#_ugfun_domain-class-ontology_view-models[view models] - domain objects that are a projection of some state held by the database, in support a particular use case; for example `CustomerDashboard` (to pull together commonly accessed information about a customer).
+
+* xref:../ugfun/ugfun.adoc#_ugfun_domain-class-ontology_mixins[mixins] - allow functionality to be "contributed" in the UI by one module to another object, similar to traits or extension methods provided in some programming languages.
+This is an important capability to help keep large applications decoupled.
 
 Domain classes are generally recognized using annotations.
 Apache Isis defines its own set of annotations, while entities are annotated using JDO/DataNucleus (though XML can also be used if required).
@@ -37,7 +40,6 @@ In the same way that the Java module act as a namespace for domain objects, it's
 include::_ugfun_domain-class-ontology_domain-entities.adoc[leveloffset=+1]
 include::_ugfun_domain-class-ontology_domain-services.adoc[leveloffset=+1]
 include::_ugfun_domain-class-ontology_view-models.adoc[leveloffset=+1]
-
-
+include::_ugfun_domain-class-ontology_mixins.adoc[leveloffset=+1]
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/9e1ea1b6/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_domain-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_domain-services.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_domain-services.adoc
index e89b754..25b27db 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_domain-services.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_domain-services.adoc
@@ -14,12 +14,14 @@ In Apache Isis domain services have several responsibilities:
 - they provide other services (eg performing calculations, attach a barcode, send an email etc).
 - to implement an SPI of the framework, most notably cross-cutting concerns such as security, command profiling, auditing and publishing.
 
-It's worth extending the xref:../ugfun/ugfun.adoc#_ugfun_core-concepts_philosophy_hexagonal-architecture[Hexagonal Architecture] to show where domain services -- and in particular the domain services provided by link:http://www.isisaddons.org[Isis Addons] (non-ASF) -- fit in:
+It's worth extending the xref:../ugfun/ugfun.adoc#_ugfun_core-concepts_philosophy_hexagonal-architecture[Hexagonal Architecture] to show where domain services fit in:
 
 .The hexagonal architecture with Isis addons
-image::{_imagesdir}how-tos/domain-services/hexagonal-architecture-addons.png[width="700px"]
+image::{_imagesdir}core-concepts/philosophy/hexagonal-architecture-addons.png[width="700px"]
 
-The (non-ASF) link:http://isisaddons.org[Isis Addons] are a good source of domain services, providing SPI implementations of the common cross-cutting concerns, and also a number of APIs for domain objects to invoke (eg tags, excel, settings).  Of course, you can also write your own domain services as well, for example to interface with some external CMS system, say.
+The (non-ASF) link:http://isisaddons.org[Isis Addons] provide SPI implementations of the common cross-cutting concerns.
+They also provide a number of APIs for domain objects to invoke (not shown in the diagram).
+You can also write your own domain services as well, for example to interface with some external CMS system, say.
 
 
 
@@ -38,9 +40,10 @@ The application provides the `@DomainService(nature=...)` annotation that helps
 Pulling all the above together, here are our suggestions as to how you should organize your domain services.
 
 
-=== Factory and Repository
+[[__ugfun_domain-class-ontology_domain-services_factory-and-repository]]
+== Factory and Repository
 
-The factory/repository uses an injected `DomainObjectContainer` to both instantiate new objects and to query the database for existing objects of a given entity type.  It is not visible in UI, rather other services delegate to it.
+The factory/repository uses an injected xref:../rgsvc/rgsvc.adoc#_rgsvc_api_RepositoryService[`RepositoryService`] to both instantiate new objects and to query the database for existing objects of a given entity type.  It is not visible in UI, rather other services delegate to it.
 
 We suggest naming such classes `XxxRepository`, eg:
 
@@ -52,7 +55,7 @@ We suggest naming such classes `XxxRepository`, eg:
 )
 public CustomerRepository {
     public List<Customer> findCustomerBy...(...) {
-        return allMatches(...);
+        return repositoyService.allMatches(...);
     }
     public Customer newCustomer(...) {
         Customer Customer = container.newTransientInstance(Customer.class);
@@ -61,10 +64,10 @@ public CustomerRepository {
         return Customer;
     }
     public List<Customer> allCustomers() {
-        return container.allInstances(Customer.class);
+        return repositoryService.allInstances(Customer.class);
     }
     @Inject
-    DomainObjectContainer container;
+    RepositoryService repositoryService;
 }
 ----
 <1> interacted with only programmatically by other objects in the domain layer.
@@ -72,8 +75,8 @@ public CustomerRepository {
 There is no need to annotate the actions; they are implicitly hidden because of the domain service's nature.
 
 
-
-=== Menu
+[[__ugfun_domain-class-ontology_domain-services_menu]]
+== Menu
 
 Menu services provide actions to be rendered on the menu.
 
@@ -137,10 +140,19 @@ Note also that while there's nothing to stop `VIEW_MENU` domain services being i
 
 
 
-=== Contributions
+[[__ugfun_domain-class-ontology_domain-services_contributions]]
+== Contributions (deprecated)
+
 
 Services can contribute either actions, properties or collections, based on the type of their parameters.
 
+[TIP]
+====
+Contributed services can instead be implemented as
+xref:../ugfun/ugfun.adoc#_ugfun_domain-class-ontology_mixins[mixins].
+As such, contributed services should be considered as deprecated.
+====
+
 We suggest naming such classes `XxxContributions`, eg:
 
 [source,java]
@@ -152,7 +164,7 @@ We suggest naming such classes `XxxContributions`, eg:
     menuOrder="10",
     name="...",
 }
-public OrderContributions {
+public class OrderContributions {
     @Action(semantics=SemanticsOf.SAFE)
     @ActionLayout(contributed=Contributed.AS_ASSOCIATION)       // <2>
     @CollectionLayout(render=RenderType.EAGERLY)
@@ -172,7 +184,10 @@ More information about contributions can be found xref:../ugfun/ugfun.adoc#_ugfu
 about using contributions and mixins to keep your domain application decoupled can be found xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_contributions[here] and xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_mixins[here].
 
 
-=== Event Subscribers
+
+
+[[__ugfun_domain-class-ontology_domain-services_event-subscribers]]
+== Event Subscribers
 
 Event subscribers can both veto interactions (hiding members, disabling members or validating changes), or can react to interactions (eg action invocation or property edit).
 
@@ -187,7 +202,7 @@ We suggest naming such classes `XxxSubscriptions`, eg:
     menuOrder="10",
     name="...",
 }
-public CustomerOrderSubscriptions {
+public class CustomerOrderSubscriptions {
     @com.google.common.eventbus.Subscribe
     public void on(final Customer.DeletedEvent ev) {
         Customer customer = ev.getSource();

http://git-wip-us.apache.org/repos/asf/isis/blob/9e1ea1b6/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_mixins.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_mixins.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_mixins.adoc
index abecbd5..0acc6cb 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_mixins.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_mixins.adoc
@@ -52,3 +52,5 @@ public class Customer_orders {                              // <2>
 This could also be an interface.
 <4> Indicates that the action should be interpreted as a collection.
 This requires that the action has safe semantics, ie does not alter state/no side-effects.
+
+There is further discussion of mixins in the xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_mixins[beyond the basics] guide.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/9e1ea1b6/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/philosophy/hexagonal-architecture-addons.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/philosophy/hexagonal-architecture-addons.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/philosophy/hexagonal-architecture-addons.png
new file mode 100644
index 0000000..ff271e9
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/philosophy/hexagonal-architecture-addons.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/9e1ea1b6/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/philosophy/hexagonal-architecture.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/philosophy/hexagonal-architecture.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/philosophy/hexagonal-architecture.png
index d8b28bd..9d9a2c6 100644
Binary files a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/philosophy/hexagonal-architecture.png and b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/philosophy/hexagonal-architecture.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/9e1ea1b6/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/philosophy/hexagonal-architecture.pptx
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/philosophy/hexagonal-architecture.pptx b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/philosophy/hexagonal-architecture.pptx
index 3eb0aad..f6c7adb 100644
Binary files a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/philosophy/hexagonal-architecture.pptx and b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/philosophy/hexagonal-architecture.pptx differ

[50/58] [abbrv] isis git commit: fixes FIXMEs in ugodn, rearranging some content

[da...@apache.org]

fixes FIXMEs in ugodn, rearranging some content


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/cf86b157
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/cf86b157
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/cf86b157

Branch: refs/heads/wip
Commit: cf86b157d0e37ee669234da53f0f2354e8591a11
Parents: d9de887
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Thu Apr 20 07:46:30 2017 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Thu Apr 20 09:09:31 2017 +0100

----------------------------------------------------------------------
 .../src/main/asciidoc/guides/dg/_dg_ide.adoc    |  3 +-
 .../asciidoc/guides/dg/_dg_ide_eclipse.adoc     |  2 +-
 .../_rgfis_spi_ContentNegotiationService.adoc   |  2 +-
 .../guides/ugodn/_ugodn_configuring.adoc        |  3 +-
 .../_ugodn_configuring_persistence-xml.adoc     | 28 ++++++++++++-
 .../guides/ugodn/_ugodn_hints-and-tips.adoc     |  2 -
 ...ndling-mandatory-properties-in-subtypes.adoc | 44 --------------------
 ..._ugodn_hints-and-tips_mapping-to-a-view.adoc |  9 ----
 .../guides/ugodn/_ugodn_jdo-mappings.adoc       |  2 +
 ...ppings_mandatory-properties-in-subtypes.adoc | 44 ++++++++++++++++++++
 .../_ugodn_jdo-mappings_mapping-to-a-view.adoc  | 18 ++++++++
 11 files changed, 97 insertions(+), 60 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/cf86b157/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide.adoc
index db76f89..ca81d39 100644
--- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide.adoc
@@ -7,7 +7,8 @@
 
 
 
-The vast majority of Java developers use an IDE to assist with developing their code, and we highly recommend that you do like wise as you develop your Apache Isis applications using an IDE.  Apache Isis is built with Maven, and all modern IDEs can import Maven projects.
+The vast majority of Java developers use an IDE to assist with developing their code, and we highly recommend that you do likewise as you develop your Apache Isis applications using an IDE.
+Apache Isis is built with Maven, and all modern IDEs can import Maven projects.
 
 This chapter shows how to setup and use two of the most popular IDEs, IntelliJ IDEA and Eclipse.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/cf86b157/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_eclipse.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_eclipse.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_eclipse.adoc
index a3f0dab..43ff34f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_eclipse.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_eclipse.adoc
@@ -90,7 +90,7 @@ When the enhancer runs, it will print out to the console:
 image::{_imagesdir}eclipse/eclipse-120-console.png[width="500px",link="{_imagesdir}/appendices/dev-env/eclipse/eclipse-120-console.png"]
 
 
-
+[[__dg_ide_eclipse_workaround-for-path-limits]]
 === Workaround for path limits (the DN plugin to use the persistence.xml)
 
 If running on Windows then the DataNucleus plugin is very likely to hit the Windows path limit.

http://git-wip-us.apache.org/repos/asf/isis/blob/cf86b157/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_ContentNegotiationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_ContentNegotiationService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_ContentNegotiationService.adoc
index 0342d47..b4d62d7 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_ContentNegotiationService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_ContentNegotiationService.adoc
@@ -18,7 +18,7 @@ Instead you need to create some sort of stable facade over your domain entities,
 +
 If the underlying entities change, then care must be taken to ensure that structure of the view model nevertheless is unchanged.
 
-* a second option is to solve the problem at the persistence layer, but defining a (SQL) view in the database and then xref:../ugodn/ugodn.adoc#_ugodn_hints-and-tips_mapping-to-a-view[mapping this] to a (read-only) entity.  Again this is surfaced by the RO viewer.  +
+* a second option is to solve the problem at the persistence layer, but defining a (SQL) view in the database and then xref:../ugodn/ugodn.adoc#_ugodn_jdo-mappings_mapping-to-a-view[mapping this] to a (read-only) entity.  Again this is surfaced by the RO viewer.  +
 +
 If the underlying tables change (as the result of a change in their corresponding domain entities) then once more the view must be refactored so that it still presents the same structure.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/cf86b157/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring.adoc
index 1734c98..5614dbe 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring.adoc
@@ -6,7 +6,8 @@
 
 Apache Isis programmatically configures DataNucleus; any Apache Isis properties with the prefix `isis.persistor.datanucleus.impl` are passed through directly to the JDO/DataNucleus objectstore (with the prefix stripped off, of course).
 
-DataNucleus will for itself also and read the `META-INF/persistence.xml`; at a minimum this defines the name of the "persistence unit".  n theory it could also hold mappings, though in Apache Isis we tend to use annotations instead.
+DataNucleus will for itself also and read the `META-INF/persistence.xml`; at a minimum this defines the name of the "persistence unit".
+In theory it could also hold mappings, though in Apache Isis we tend to use annotations instead.
 
 Furthermore, DataNucleus will search for various other XML mapping files, eg `mappings.jdo`.  A full list can be found http://www.datanucleus.org/products/datanucleus/jdo/metadata.html[here].  The metadata in these XML can be used to override the annotations of annotated entities; see xref:../ugbtb/ugbtb.adoc#_ugbtb_other-techniques_overriding-jdo-annotations[Overriding JDO Annotatons] for further discussion.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/cf86b157/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_persistence-xml.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_persistence-xml.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_persistence-xml.adoc
index db4a42e..cbfbad4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_persistence-xml.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_persistence-xml.adoc
@@ -5,6 +5,32 @@
 :_imagesdir: images/
 
 
-NOTE: FIXME
 
+DataNucleus will for itself also and read the `META-INF/persistence.xml`.
+In theory it can hold mappings and even connection strings.
+However, with Apache Isis we tend to use annotations instead and externalize connection strings. so its definition is extremely simply, specifying just the name of the "persistence unit".
 
+Here's the one provided by the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]:
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8" ?>
+<persistence xmlns="http://java.sun.com/xml/ns/persistence"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd" version="1.0">
+
+    <persistence-unit name="simple">
+    </persistence-unit>
+</persistence>
+----
+
+Normally all one needs to do is to change the `persistence-unit` name.
+
+[TIP]
+====
+If you use Eclipse IDE on Windows then xref:../dg/dg.adoc#__dg_ide_eclipse_workaround-for-path-limits[note the importance] of the `persistence.xml` file to make DataNucleus enhancer work correctly.
+====
+
+
+
+See link:http://www.datanucleus.org/products/datanucleus/jdo/persistence.html#persistenceunit[DataNucleus' documentation] on `persistence.xml` to learn more.

http://git-wip-us.apache.org/repos/asf/isis/blob/cf86b157/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips.adoc
index 1efd665..7f02c3b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips.adoc
@@ -23,8 +23,6 @@ See also hints-n-tips chapters in the:
 
 
 include::_ugodn_hints-and-tips_overriding-jdo-annotations.adoc[leveloffset=+1]
-include::_ugodn_hints-and-tips_handling-mandatory-properties-in-subtypes.adoc[leveloffset=+1]
-include::_ugodn_hints-and-tips_mapping-to-a-view.adoc[leveloffset=+1]
 
 include::_ugodn_hints-and-tips_subtype-entity-not-fully-populated.adoc[leveloffset=+1]
 include::_ugodn_hints-and-tips_java8.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/cf86b157/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_handling-mandatory-properties-in-subtypes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_handling-mandatory-properties-in-subtypes.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_handling-mandatory-properties-in-subtypes.adoc
deleted file mode 100644
index eff87e0..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_handling-mandatory-properties-in-subtypes.adoc
+++ /dev/null
@@ -1,44 +0,0 @@
-[[_ugodn_hints-and-tips_handling-mandatory-properties-in-subtypes]]
-= Handling Mandatory Properties in Subtypes
-: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/
-
-
-
-If you have a hierarchy of classes then you need to decide which inheritance strategy to use.
-
-* "table per hierarchy", or "rollup" (`InheritanceStrategy.SUPERCLASS_TABLE`) +
-+
-whereby a single table corresponds to the superclass, and also holds the properties of the subtype (or subtypes) being rolled up
-
-* "table per class" (`InheritanceStrategy.NEW_TABLE`) +
-+
-whereby there is a table for both superclass and subclass, in 1:1 correspondence
-
-* "rolldown" (`InheritanceStrategy.SUBCLASS_TABLE`) +
-+
-whereby a single table holds the properties of the subtype, and also holds the properties of its supertype
-
-In the first "rollup" case, we can have a situation where - logically speaking - the property is mandatory in the subtype - but it must be mapped as nullable in the database because it is n/a for any other subtypes that are rolled up.
-
-In this situation we must tell JDO that the column is optional, but to Apache Isis we want to enforce it being mandatory. This can be done using the `@Property(optionality=Optionality.MANDATORY)` annotation.
-
-For example:
-
-[source,java]
-----
-@javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.SUPER_TABLE)
-public class SomeSubtype extends SomeSuperType {
-    @javax.jdo.annotations.Column(allowsNull="true")
-    @Property(optionality=Optionality.MANDATORY)
-    @lombok.Getter @lombok.Setter
-    private LocalDate date;
-}
-----
-
-[TIP]
-====
-The `@Property(optionality=...)` annotation is equivalent to the older but still supported `@Optional` annotation and `@Mandatory` annotations.
-====
-

http://git-wip-us.apache.org/repos/asf/isis/blob/cf86b157/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_mapping-to-a-view.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_mapping-to-a-view.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_mapping-to-a-view.adoc
deleted file mode 100644
index a50c2a0..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_mapping-to-a-view.adoc
+++ /dev/null
@@ -1,9 +0,0 @@
-[[_ugodn_hints-and-tips_mapping-to-a-view]]
-= Mapping to a View
-: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/
-
-
-NOTE: FIXME - as per Estatio's Invoice stuff
-

http://git-wip-us.apache.org/repos/asf/isis/blob/cf86b157/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings.adoc
index 7a7de94..18a8b08 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings.adoc
@@ -8,3 +8,5 @@
 
 
 include::_ugodn_jdo-mappings_1-to-m-bidirectional-relationships.adoc[leveloffset=+1]
+include::_ugodn_jdo-mappings_mandatory-properties-in-subtypes.adoc[leveloffset=+1]
+include::_ugodn_jdo-mappings_mapping-to-a-view.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/cf86b157/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings_mandatory-properties-in-subtypes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings_mandatory-properties-in-subtypes.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings_mandatory-properties-in-subtypes.adoc
new file mode 100644
index 0000000..1720d5f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings_mandatory-properties-in-subtypes.adoc
@@ -0,0 +1,44 @@
+[[_ugodn_jdo-mappings_mandatory-properties-in-subtypes]]
+= Mandatory Properties in Subtypes
+: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/
+
+
+
+If you have a hierarchy of classes then you need to decide which inheritance strategy to use.
+
+* "table per hierarchy", or "rollup" (`InheritanceStrategy.SUPERCLASS_TABLE`) +
++
+whereby a single table corresponds to the superclass, and also holds the properties of the subtype (or subtypes) being rolled up
+
+* "table per class" (`InheritanceStrategy.NEW_TABLE`) +
++
+whereby there is a table for both superclass and subclass, in 1:1 correspondence
+
+* "rolldown" (`InheritanceStrategy.SUBCLASS_TABLE`) +
++
+whereby a single table holds the properties of the subtype, and also holds the properties of its supertype
+
+In the first "rollup" case, we can have a situation where - logically speaking - the property is mandatory in the subtype - but it must be mapped as nullable in the database because it is n/a for any other subtypes that are rolled up.
+
+In this situation we must tell JDO that the column is optional, but to Apache Isis we want to enforce it being mandatory. This can be done using the `@Property(optionality=Optionality.MANDATORY)` annotation.
+
+For example:
+
+[source,java]
+----
+@javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.SUPER_TABLE)
+public class SomeSubtype extends SomeSuperType {
+    @javax.jdo.annotations.Column(allowsNull="true")
+    @Property(optionality=Optionality.MANDATORY)
+    @lombok.Getter @lombok.Setter
+    private LocalDate date;
+}
+----
+
+[TIP]
+====
+The `@Property(optionality=...)` annotation is equivalent to the older but still supported `@Optional` annotation and `@Mandatory` annotations.
+====
+

http://git-wip-us.apache.org/repos/asf/isis/blob/cf86b157/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings_mapping-to-a-view.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings_mapping-to-a-view.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings_mapping-to-a-view.adoc
new file mode 100644
index 0000000..e9311f4
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings_mapping-to-a-view.adoc
@@ -0,0 +1,18 @@
+[[_ugodn_jdo-mappings_mapping-to-a-view]]
+= Mapping to a View
+: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/
+
+
+JDO/DataNucleus supports the ability to map the entity that is mapped to a view rather than a database table.
+Moreover, DataNucleus itself can create/maintain this view.
+
+One use case for this is to support use cases which act upon aggregate information.
+An link:https://github.com/estatio/estatio/blob/b77d0b03ec86463227ba90f8341299066ddba69f/estatioapp/module/lease/dom/src/main/java/org/estatio/dom/lease/invoicing/viewmodel/InvoiceSummaryForPropertyDueDateStatus.java#L57[example] is in the (non-ASF) http://github.com/estatio/estatio[Estatio] application, which uses a view to define an "invoice run": a representatoin of all pending invoices to be sent out for a particular shopping centre.
+(Note that example also shows the entity as being "non-durable", but if the view is read/write then -- I think -- that this isn't necessary required).
+
+
+For more on this topic, see the link:http://www.datanucleus.org/products/datanucleus/jdo/mapping.html#schema_rdbms_views[DataNucleus documentation].
+
+

[21/58] [abbrv] isis git commit: ISIS-1521: working on ugfun.adoc

[da...@apache.org]

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_mixins.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_mixins.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_mixins.adoc
new file mode 100644
index 0000000..1a0a9a3
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_mixins.adoc
@@ -0,0 +1,346 @@
+[[_ugfun_programming-model_mixins]]
+= Mixins
+
+: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/
+
+
+
+
+Syntactically, a mixin is defined using either the xref:../rgant/rgant.adoc#_rgant_Mixin[`@Mixin`] annotation or using xref:../rgant/rgant.adoc#_rgant_DomainObject_nature[`@DomainObject#nature()`] attribute (specifying a nature of `Nature.MIXIN`).
+
+
+
+[source,java]
+----
+@Mixin(method="coll")                                       // <1>
+public class Customer_orders {                              // <2>
+
+    private final Customer customer;
+    public Customer_orders(final Customer customer) {       // <3>
+        this.customer = customer;
+    }
+
+    @Action(semantics=SemanticsOf.SAFE)                     // <4>
+    @ActionLayout(contributed=Contributed.AS_ASSOCIATION)   // <4>
+    @CollectionLayout(render=RenderType.EAGERLY)
+    public List<Order> coll() {                             // <1>
+        return repositoryService.findOrdersFor(customer);
+    }
+
+    @Inject
+    RepositoryService repositoryService;
+}
+----
+<1> indicates that this is a mixin, with "coll" as the name of the main method
+<2> The contributed member is inferred from the name, after the "_"; in other words "orders"
+<3> The mixee is `Customer`.
+This could also be an interface.
+<4> Indicates that the action should be interpreted as a collection.
+This requires that the action has safe semantics, ie does not alter state/no side-effects.
+
+
+
+
+
+
+
+''''
+''''
+
+== Contributed services
+
+Contributed services provide many of the same benefits as xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_mixins[mixins];
+indeed mixins are an evolution and refinement of the contributions concept.
+
+[WARNING]
+====
+It's possible that contributions may be deprecated and eventually removed in a future version of the framework, to be replaced entirely by mixins.
+====
+
+The main difference between contributed services and mixins is that the actions of a contributed service will
+contribute to _all_ the parameters of its actions, whereas a mixin only contributes to the type accepted in its
+constructor.  Also, contributed services are long-lived
+singletons, whereas mixins are instantiated as required (by the framework) and then discarded almost immediately.
+
+[NOTE]
+====
+There's further useful information on contributed services in the reference guide, discussing the xref:../rgant/rgant.adoc#_rgant-DomainService_nature[@DomainService#nature()] attribute, for the `NatureOfService.VIEW_CONTRIBUTIONS_ONLY` nature.
+====
+
+
+=== Syntax
+
+Any n-parameter action provided by a service will automatically be contributed to the list of actions for each of its (entity) parameters. From the viewpoint of the entity the action is called a contributed action.
+
+For example, given a service:
+
+[source,java]
+----
+public interface Library {
+    public Loan borrow(Loanable l, Borrower b);
+}
+----
+
+and the entities:
+
+[source,java]
+----
+public class Book implements Loanable { ... }
+----
+
+and
+
+[source,java]
+----
+public class LibraryMember implements Borrower { ... }
+----
+
+then the `borrow(...)` action will be contributed to both `Book` and to `LibraryMember`.
+
+This is an important capability because it helps to decouple the concrete classes from the services.
+
+If necessary, though, this behaviour can be suppressed by annotating the service action with `@org.apache.isis.applib.annotations.NotContributed`.
+
+For example:
+
+[source,java]
+----
+public interface Library {
+    @NotContributed
+    public Loan borrow(Loanable l, Borrower b);
+}
+----
+
+If annotated at the interface level, then the annotation will be inherited by every concrete class. Alternatively the annotation can be applied at the implementation class level and only apply to that particular implementation.
+
+Note that an action annotated as being `@NotContributed` will still appear in the service menu for the service. If an action should neither be contributed nor appear in service menu items, then simply annotate it as `@Hidden`.
+
+
+## Contributed Action
+
+NOTE: FIXME
+
+## Contributed Property
+
+NOTE: FIXME
+
+## Contributed Collection
+
+NOTE: FIXME
+
+
+
+
+
+== Contributed Collection
+
+The example below shows how to contribute a collection:
+
+[source,java]
+----
+@Mixin
+public class DocumentHolderDocuments {
+
+    private final DocumentHolder holder;
+    public DocumentHolderDocuments(DocumentHolder holder) { this.holder = holder; }
+
+    @Action(semantics=SemanticsOf.SAFE)                         // <1>
+    @ActionLayout(contributed = Contributed.AS_ASSOCIATION)     // <2>
+    @CollectionLayout(render = RenderType.EAGERLY)
+    public List<Document> documents() {                         // <3>
+        ...
+    }
+    public boolean hideDocuments() { ... }                      // <4>
+}
+----
+<1> required; actions that have side-effects cannot be contributed as collections
+<2> required; otherwise the mixin will default to being rendered as an action
+<3> must accept no arguments.
+    The mixin is a collection rather than a property because the return type is a collection, not a scalar.
+<4> supporting methods follow the usual naming conventions.
+    (That said, in the case of collections, because the collection is derived/read-only, the only supporting method that is relevant is `hideXxx()`).
+
+The above will result in a contributed collection for all types that implement/extend from `DocumentHolder` (so is probably for a mixin across modules).
+
+
+
+== Contributed Property
+
+Contributed properties are defined similarly, for example:
+
+[source,java]
+----
+@Mixin
+public class DocumentHolderMostRecentDocument {
+
+    private final DocumentHolder holder;
+    public DocumentHolderDocuments(DocumentHolder holder) { this.holder = holder; }
+
+    @Action(semantics=SemanticsOf.SAFE)                         // <1>
+    @ActionLayout(contributed = Contributed.AS_ASSOCIATION)     // <2>
+    public Document> mostRecentDocument() {                     // <3>
+        ...
+    }
+    public boolean hideMostRecentDocument() { ... }             // <4>
+}
+----
+<1> required; actions that have side-effects cannot be contributed as collections
+<2> required; otherwise the mixin will default to being rendered as an action
+<3> must accept no arguments.
+    The mixin is a property rather than a collection because the return type is a scalar.
+<4> supporting methods follow the usual naming conventions.
+    (That said, in the case of properties, because the property is derived/read-only, the only supporting method that is relevant is `hideXxx()`).
+
+
+== Contributed Action
+
+Contributed properties are defined similarly, for example:
+
+[source,java]
+----
+@Mixin
+public class DocumentHolderAddDocument {
+
+    private final DocumentHolder holder;
+    public DocumentHolderDocuments(DocumentHolder holder) { this.holder = holder; }
+
+    @Action()
+    @ActionLayout(contributed = Contributed.AS_ACTION)          // <1>
+    public Document> addDocument(Document doc) {
+        ...
+    }
+    public boolean hideAddDocument() { ... }                    // <2>
+}
+----
+<1> recommended
+<2> supporting methods follow the usual naming conventions.
+
+
+== Inferred Name
+
+Where the mixin follows the naming convention `SomeType_mixinName` then the method name can be abbreviated to "$$".
+The mixin name is everything after the last '_'.
+
+For example:
+
+[source,java]
+----
+@Mixin
+public class DocumentHolder_documents {
+
+    private final DocumentHolder holder;
+    public DocumentHolder_documents(DocumentHolder holder) { this.holder = holder; }
+
+    @Action(semantics=SemanticsOf.SAFE)
+    @ActionLayout(contributed = Contributed.AS_ASSOCIATION)
+    @CollectionLayout(render = RenderType.EAGERLY)
+    public List<Document> $$() {                                    // <1>
+        ...
+    }
+    public boolean hide$$() { ... }                                 // <2>
+}
+----
+<1> using "$$" as the reserved method name
+<2> supporting methods as usual
+
+The character "$" is also recognized as a separator between the mixin type and mixin name.
+This is useful for mixins implemented as nested static types, discussed below.
+
+
+== As Nested Static Classes
+
+As noted in the introduction, while mixins were originally introduced as a means of allowing contributions from one module to the types of another module, they are also a convenient mechanism for grouping functionality/behaviour against a concrete type.
+All the methods and supporting methods end up in a single construct, and the dependency between that functionality and the rest of the object is made more explicit.
+
+When using mixins in this fashion, it is idiomatic to write the mixin as a nested static class, using the naming convention described above to reduce duplication.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+
+    @Mixin
+    public static class placeOrder {                                            // <1>
+
+        private final Customer customer;
+        public documents(Customer customer) { this.customer = customer; }       // <2>
+
+        @Action
+        @ActionLayout(contributed = Contributed.AS_ACTION)
+        public List<Order> $$(Product p, int quantity) {                        // <3>
+            ...
+        }
+        public boolean hide$$() { ... }                                         // <4>
+        public String validate0$$(Product p) { ...  }
+    }
+}
+----
+<1> Prior to `1.13.2`, had to be prefixed by an "_"; this is no longer required because "$" is also recognized as a way of parsing the class name in order to infer the mixin's name (eg `Customer$placeOrder`).
+<2> typically contributed to concrete class
+<3> using the "$$" reserved name
+<4> supporting methods as usual
+
+
+Moreover, the mixin class can be capitalized if desired.
+Thus:
+
+[source,java]
+----
+public class Customer {
+
+    @Mixin
+    public static class PlaceOrder {                                            // <1>
+
+        private final Customer customer;
+        public documents(Customer customer) { this.customer = customer; }       // <2>
+
+        @Action
+        @ActionLayout(contributed = Contributed.AS_ACTION)
+        public List<Order> $$(Product p, int quantity) {                        // <3>
+            ...
+        }
+        public boolean hide$$() { ... }                                         // <4>
+        public String validate0$$(Product p) { ...  }
+    }
+}
+----
+
+
+In other words, all of the following are allowed:
+
+* `public static class Documents { ... }`
+* `public static class documents { ... }`
+* `public static class _Documents { ... }`
+* `public static class _documents { ... }`
+
+The reserved method name "$$" can also be changed using xref:../rgant/rgant.adoc#_rgant_Mixin_method[`@Mixin#method()`] or xref:../rgant/rgant.adoc#_rgant_DomainObject_mixinMethod[`@DomainObject#mixinMethod()`].
+
+
+
+
+
+
+
+
+== Programmatic usage
+
+When a domain object is rendered, the framework will automatically instantiate all required mixins and delegate to them
+dynamically.  If writing integration tests or fixtures, or (sometimes) just regular domain logic, then you may need to
+instantiate mixins directly.
+
+For this you can use the
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-creation-api[`DomainObjectContainer#mixin(...)`
+method.  For example:
+
+[source,java]
+----
+DocumentHolder_documents mixin = container.mixin(DocumentHolder_documents.class, customer);
+----
+
+The xref:../ugtst/ugtst.adoc#__ugtst_integ-test-support_bootstrapping_IntegrationTestAbstract[`IntegrationTestAbstract`] and
+xref:../rgcms/rgcms.adoc#_rgcms_classes_super_FixtureScript[`FixtureScript`] classes both provide a `mixin(...)` convenience
+method.
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_properties-vs-parameters.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_properties-vs-parameters.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_properties-vs-parameters.adoc
new file mode 100644
index 0000000..e588c44
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_properties-vs-parameters.adoc
@@ -0,0 +1,38 @@
+[[_ugfun_programming-model_properties-vs-parameters]]
+= Properties vs Parameters
+: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/
+
+
+In many cases the value types of properties and of action parameters align.
+For example, a `Customer` entity might have a `surname` property, and there might also be corresponding `changeSurname`.
+Ideally we want the surname property and surname action parameter to use the same value type.
+
+Since JDO/DataNucleus handles persistence, its annotations are requiredto specify semantics such as optionality or maximum length on properties.
+However, they cannot be applied to action parameters.
+It is therefore necessary to use Apache Isis' equivalent annotations for action parameters.
+
+The table below summarises the equivalence of some of the most common cases.
+
+.Comparing annotations of Properties vs Action Parameters
+[cols="2,3,3", options="header"]
+|===
+|value type/semantic
+|(JDO) property
+|action parameter
+
+|string (length)
+|`@javax.jdo.annotations.Column(length=50)`
+|`@javax.jdo.annotations.Parameter(maxLength=50)`
+
+|big decimal (precision)
+|`@javax.jdo.annotations.Column(scale=2)`
+|`@javax.validation.constraints.Digits(fraction=2)`
+
+|optionality
+|`@Column(allowsNull="true")`
+|`@Nullable` or `ParameterLayout(optionality=Optionality.OPTIONAL`) (also `@Optional`, now deprecated)
+|===
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_properties.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_properties.adoc
new file mode 100644
index 0000000..0ab9bad
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_properties.adoc
@@ -0,0 +1,369 @@
+[[_ugfun_programming-model_properties]]
+= Property
+: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/
+
+
+A property is an instance variable of a domain object, of a scalar type, that holds some state about either a xref:../ugfun/ugfun.adoc#__ugfun_programming-model_class-definition_entities[domain entity] or a xref:../ugfun/ugfun.adoc#__ugfun_programming-model_class-definition_view-models[view model].
+
+For example, a ``Customer``'s `firstName` would be a property, as would their `accountCreationDate` that they created their account.
+All properties have at least a "getter" method, and most properties have also a "setter" method (meaning that they are mutable).
+Properties that do _not_ have a setter method are derived properties, and so are not persisted.
+
+Formally speaking, a property is simply a regular JavaBean getter, returning a scalar value recognized by the framework.
+Most properties (those that are editable/modifiable) will also have a setter and (if persisted) a backing instance field.
+And most properties will also have a number of annotations:
+
+* Apache Isis defines its own set own `@Property` annotation for capturing domain semantics.
+It also provides a `@PropertyLayout` for UI hints (though the information in this annotation may instead be provided by a supplementary xref:../ugvw/ugvw.adoc#_ugvw_layout[`.layout.xml`] file
+
+* the properties of domain entities are often annotated with the JDO/DataNucleus `@javax.jdo.annotations.Column` annotation.
+For property references, there may be other annotations to indicate whether the reference is bidirectional.
+It's also possible (using annotations) to define a link table to hold foreign key columns.
+
+* for the properties of view models, then JAXB annotations such as `@javax.xml.bind.annotation.XmlElement` will be present
+
+Apache Isis recognises some of these annotations for JDO/DataNucleus and JAXB and infers some domain semantics from them (for example, the maximum allowable length of a string property).
+
+Since writing getter and setter methods adds quite a bit of boilerplate, it's common to use link:https://projectlombok.org/[Project Lombok] to code generate these methods at compile time (using Java's annotation processor) simply by adding the `@lombok.Getter` and `@lombok.Setter` annotations to the field.
+The xref:guides/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] uses this approach.
+
+
+[[__ugfun_programming-model_properties_value-vs-reference-types]]
+== Value vs Reference Types
+
+Properties can be either a value type (strings, int, date and so on) or be a reference to another object (for example, an `Order` referencing the `Customer` that placed it).
+
+For example, to map a string value type:
+
+[source,java]
+----
+@lombok.Getter @lombok.Setter       // <1>
+private String notes;
+----
+<1> using link:https://projectlombok.org/[Project Lombok] annotations to reduce boilerplate
+
+You could also add the `@Property` annotation if you wished:
+
+[source,java]
+----
+@Property
+@lombok.Getter @lombok.Setter
+private String notes;
+----
+
+Although in this case it is not required (none of its attributes have been set).
+
+Or to map a reference type:
+
+[source,java]
+----
+@lombok.Getter @lombok.Setter
+private Customer customer;
+----
+
+It's ok for a xref:../ugfun/ugfun.adoc#__ugfun_programming-model_class-definition_entities[domain entity] to reference another domain entity, and for a xref:../ugfun/ugfun.adoc#__ugfun_programming-model_class-definition_view-models[view model] to reference both view model and domain entities.
+However, it isn't valid for a domain entity to hold a persisted reference to view model (DataNucleus will not know how to persist that view model).
+
+[NOTE]
+====
+For further details on mapping associations, see the JDO/DataNucleus documentation for link:http://www.datanucleus.org/products/accessplatform_4_1/jdo/orm/one_to_many.html[one-to-many] associations, link:http://www.datanucleus.org/products/accessplatform_4_1/jdo/orm/many_to_one.html[many-to-one] associations, link:http://www.datanucleus.org/products/accessplatform_4_1/jdo/orm/many_to_many.html[many-to-many] associations, and so on.
+====
+
+For domain entities, the annotations for mapping value types tend to be different for properties vs action parameters, because JDO annotations are only valid on properties.
+The table in the xref:../ugfun/ugfun.adoc#_ugfun_programming-model_properties-vs-parameters[Properties vs Parameters] section provides a handy reference of each.
+
+
+[[__ugfun_programming-model_properties_optional-properties]]
+== Optional Properties
+
+(For domain entities) JDO/DataNucleus' default is that a property is assumed to be mandatory if it is a primitive type (eg `int`, `boolean`), but optional if a reference type (eg `String`, `BigDecimal` etc).
+To override optionality in JDO/DataNucleus the `@Column(allowsNull="...")` annotations is used.
+
+Apache Isis on the other hand assumes that all properties (and action parameters, for that matter) are mandatory, not optional.
+These defaults can also be overridden using Apache Isis' own annotations, specifically `@Property(optionality=...)`, or (because it's much less verbose) using `@javax.annotation.Nullable`.
+
+These different defaults can lead to incompatibilities between the two frameworks.
+To counteract that, Apache Isis also recognizes and honours JDO's `@Column(allowsNull=...)`.
+
+For example, you can write:
+
+[source,java]
+----
+@javax.jdo.annotations.Column(allowsNull="true")
+@lombok.Getter @lombok.Setter
+private LocalDate date;
+----
+
+rather than the more verbose:
+
+[source,java]
+----
+@javax.jdo.annotations.Column(allowsNull="true")
+@Property(optionality=Optionality.OPTIONAL)
+@lombok.Getter @lombok.Setter
+private LocalDate date;
+----
+
+The framework will search for any incompatibilities in optionality (whether specified explicitly or defaulted implicitly) between Isis' defaults and DataNucleus, and refuse to boot if any are found (fail fast).
+
+[[__ugfun_programming-model_properties_editable-properties]]
+== Editable Properties
+
+Apache Isis provides the capability to allow individual properties to be modified.
+This is specified using the `@Property(editing=...)` attribute.
+
+For example:
+
+[source,java]
+----
+@Property(editing = Editing.ENABLED)
+@lombok.Getter @lombok.Setter
+private String notes;
+----
+
+If this is omitted then whether editing is enabled or disabled is defined globally, in the `isis.properties` configuration file; see xref:../rgcfg/rgcfg.adoc#__rgcfg_configuring-core_isis-objects-editing[reference configuration guide] for further details.
+
+
+[[__ugfun_programming-model_properties_ignoring-properties]]
+== Ignoring Properties
+
+By default Apache Isis will automatically render all properties in the xref:../ugvw/ugvw.adoc[UI] or in the xref:../ugvro/ugvro.adoc[REST API].
+To get Apache Isis to ignore a property (exclude it from its metamodel), annotate the getter using `@Programmatic`.
+
+Similarly, you can tell JDO/DataNucleus to ignore a property using the `@javax.jdo.annotations.NotPersistent` annotation.
+This is independent of Apache Isis; in other words that property will still be rendered in the UI (unless also annotated with `@Programmatic`).
+
+For view models, you can tell JAXB to ignore a property using the `@javax.xml.bind.annotation.XmlTransient` annotation.
+Again, this is independent of Apache Isis.
+
+
+[[__ugfun_programming-model_properties_derived-properties]]
+== Derived Properties
+
+Derived properties are those with a getter but no setter.
+Provided that the property has not been annotated with `@Programmatic`, these will still be rendered in the UI, but they will be read-only (not editable) and their state will not be persisted.
+
+Subtly different, it is also possible to have non-persisted but still editable properties.
+In this case you will need a getter and a setter, but with the getter annotated using `@NotPersistent`.
+The implementation of these getters and setters will most likely persist state using other properties (which might be hidden from view using `@Programmatic`).
+
+For example:
+
+[source,java]
+----
+@javax.jdo.annotations.NotPersistent
+@Property(editing=Editing.ENABLED)
+public String getAddress() { return addressService.toAddress( getLatLong() ); }             // <1>
+public void setAddress(String address) { setLatLong(addressService.toLatLong(address)); }
+
+@javax.jdo.annotations.Column
+private String latLong;
+@Programmatic
+public String getLatLong() { return latLong; }                                              // <2>
+public void setLatLong(String latLong) { this.latLong = latLong; }
+
+@javax.inject.Inject
+AddressService addressService;                                                              // <3>
+----
+<1> the representation of the address, in human readable form, eg "10 Downing Street, London, UK"
+<2> the lat/long representation of the address, eg "51.503363;-0.127625"
+<3> an injected service that can convert to/from address and latLong.
+
+
+
+[[__ugfun_programming-model_properties_datatypes]]
+== Data types
+
+This section shows specific considerations for various datatypes, in particular how to annotate them for DataNucleus mapping to the persistence object store.
+
+
+
+[[__ugfun_programming-model_properties_datatypes_strings]]
+=== ``String``s (Length)
+
+By default JDO/DataNucleus will map string properties to a `VARCHAR(255)`.
+To limit the length, use the `@Column(length=...)` annotation.
+
+For example:
+
+[source,java]
+----
+@javax.jdo.annotations.Column(length=50)
+@lombok.Getter @lombok.Setter
+private String firstName
+----
+
+This is a good example of a case where Apache Isis infers domain semantics from the JDO annotation.
+
+
+
+[[__ugfun_programming-model_properties_datatypes-joda-dates]]
+=== JODA Dates
+
+Isis' JDO objectstore bundles DataNucleus' http://www.datanucleus.org/documentation/products/plugins.html[built-in support] for Joda `LocalDate` and `LocalDateTime` datatypes, meaning that entity properties of these types will be persisted as appropriate data types in the database tables.
+
+It is, however, necessary to annotate your properties with `@javax.jdo.annotations.Persistent`, otherwise the data won't actually be persisted.
+See the link:http://db.apache.org/jdo/field_types.html[JDO docs] for more details on this.
+
+Moreover, these datatypes are _not_ in the default fetch group, meaning that JDO/DataNucleus will perform an additional `SELECT` query for each attribute.
+To avoid this extra query, the annotation should indicate that the property is in the default fetch group.
+
+For example, the `ToDoItem` (in the https://github.com/isisaddons/isis-app-todoapp[todoapp example app] (not ASF)) defines the `dueBy` property as follows:
+
+[source,java]
+----
+@javax.jdo.annotations.Persistent(defaultFetchGroup="true")
+@javax.jdo.annotations.Column(allowsNull="true")
+@Getter @Setter
+private LocalDate dueBy;
+----
+
+
+[[__ugfun_programming-model_properties_datatypes_bigdecimals]]
+=== ``BigDecimal``s (Precision)
+
+Working with `java.math.BigDecimal` properties takes a little care due to scale/precision issues.
+
+For example, suppose we have:
+
+[source,java]
+----
+@lombok.Getter @lombok.Setter
+private BigDecimal impact;
+----
+
+JDO/DataNucleus creates, at least with HSQL, the table with the field type as NUMERIC(19). No decimal digits are admitted. (Further details http://hsqldb.org/doc/2.0/guide/sqlgeneral-chapt.html#sgc_numeric_types[here]).
+
+What this implies is that, when a record is inserted, a log entry similar to this one appears:
+
+[source,java]
+----
+INSERT INTO ENTITY(..., IMPACT, ....) VALUES (...., 0.5, ....)
+----
+
+But when that same record is retrieved, the log will show that a value of "0" is returned, instead of 0.5.
+
+The solution is to explicitly add the scale to the field like this:
+
+[source,java]
+----
+@javax.jdo.annotations.Column(scale=2)
+@lombok.Getter @lombok.Setter
+private BigDecimal impact;
+----
+
+In addition, you should also set the scale of the `BigDecimal`, using `setScale(scale, roundingMode)`.
+
+More information can be found http://www.opentaps.org/docs/index.php/How_to_Use_Java_BigDecimal:_A_Tutorial[here] and http://www.tutorialspoint.com/java/math/bigdecimal_setscale_rm_roundingmode.htm[here].
+
+
+
+[[__ugfun_programming-model_properties_datatypes_blobs]]
+=== ``Blob``s
+
+Apache Isis configures JDO/DataNucleus so that the properties of type `org.apache.isis.applib.value.Blob` and `org.apache.isis.applib.value.Clob` can also be persisted.
+
+As for xref:../ugfun/ugfun.adoc#__ugfun_programming-model_properties_datatypes_joda-dates[Joda dates], this requires the `@javax.jdo.annotations.Persistent` annotation.
+However, whereas for dates one would always expect this value to be retrieved eagerly, for blobs and clobs it is not so clear cut.
+
+For example, in the `ToDoItem` class (of the https://github.com/isisaddons/isis-app-todoapp/blob/0333852ddd18ad67e3356fccf805aa442246790d/dom/src/main/java/todoapp/dom/todoitem/ToDoItem.java#L442[todoapp example app] (non-ASF) the `attachment` property is as follows:
+
+[source,java]
+----
+@javax.jdo.annotations.Persistent(defaultFetchGroup="false", columns = {
+    @javax.jdo.annotations.Column(name = "attachment_name"),
+    @javax.jdo.annotations.Column(name = "attachment_mimetype"),
+    @javax.jdo.annotations.Column(name = "attachment_bytes", jdbcType="BLOB", sqlType = "LONGVARBINARY")
+})
+@Property(
+        optionality = Optionality.OPTIONAL
+)
+@lombok.Getter @lombok.Setter
+private Blob attachment;
+----
+
+The three `@javax.jdo.annotations.Column` annotations are required because the mapping classes that Apache Isis provides (https://github.com/apache/isis/blob/isis-1.4.0/component/objectstore/jdo/jdo-datanucleus/src/main/java/org/apache/isis/objectstore/jdo/datanucleus/valuetypes/IsisBlobMapping.java#L59[IsisBlobMapping] and https://github.com/apache/isis/blob/isis-1.4.0/component/objectstore/jdo/jdo-datanucleus/src/main/java/org/apache/isis/objectstore/jdo/datanucleus/valuetypes/IsisClobMapping.java#L59[IsisClobMapping]) map to 3 columns.
+(It is not an error to omit these `@Column` annotations, but without them the names of the table columns are simply suffixed `_0`, `_1`, `_2` etc.
+
+If the `Blob` is mandatory, then use:
+
+[source,java]
+----
+@javax.jdo.annotations.Persistent(defaultFetchGroup="false", columns = {
+    @javax.jdo.annotations.Column(name = "attachment_name", allowsNull="false"),
+    @javax.jdo.annotations.Column(name = "attachment_mimetype", allowsNull="false"),
+    @javax.jdo.annotations.Column(name = "attachment_bytes",
+                                  jdbcType="BLOB", sqlType = "LONGVARBINARY",
+                                  allowsNull="false")
+})
+@Property(
+    optionality = Optionality.MANDATORY
+)
+@lombok.Getter @lombok.Setter
+private Blob attachment;
+----
+
+[NOTE]
+====
+If specifying a `sqlType` of "LONGVARBINARY" does not work, try instead "BLOB".
+There can be differences in behaviour between JDBC drivers.
+====
+
+[[__ugfun_programming-model_properties_datatypes_clobs]]
+=== ``Clob``s
+
+
+Mapping `Clob`s works in a very similar way to xref:../ugfun/ugfun.adoc#__ugfun_programming-model_properties_datatypes_blobs[``Blob``]s, but the `jdbcType` and `sqlType` attributes will, respectively, be `CLOB` and `LONGVARCHAR`:
+
+[source,java]
+----
+@javax.jdo.annotations.Persistent(defaultFetchGroup="false", columns = {
+    @javax.jdo.annotations.Column(name = "attachment_name"),
+    @javax.jdo.annotations.Column(name = "attachment_mimetype"),
+    @javax.jdo.annotations.Column(name = "attachment_chars",
+                                  jdbcType="CLOB", sqlType = "LONGVARCHAR")
+})
+private Clob doc;
+@Property(
+    optionality = Optionality.OPTIONAL
+)
+public Clob getDoc() {
+    return doc;
+}
+public void setDoc(final Clob doc) {
+    this.doc = doc;
+}
+----
+
+[NOTE]
+====
+If specifying a `sqlType` of "LONGVARCHAR" does not work, try instead "CLOB".  There can be differences in behaviour between JDBC drivers.
+====
+
+
+[[__ugfun_programming-model_properties_datatypes_mapping-to-varbinary-or-varchar]]
+=== Mapping to VARBINARY or VARCHAR
+
+Instead of mapping to a sqlType of `LONGVARBINARY` (or perhaps `BLOB`), you might instead decide to map to a `VARBINARY`.
+The difference is whether the binary data is held "on-row" or as a pointer "off-row"; with a `VARBINARY` the data is held on-row and so you will need to specify a length.
+
+For example:
+
+[source,java]
+----
+@javax.jdo.annotations.Column(name = "attachment_bytes", jdbcTypr="BLOB", sqlType = "VARBINARY", length=2048)
+----
+
+The same argument applies to `LONGVARCHAR` (or `CLOB`); you could instead map to a regular `VARCHAR`:
+
+[source,java]
+----
+@javax.jdo.annotations.Column(name = "attachment_chars", sqlType = "VARCHAR", length=2048)
+----
+Support and maximum allowed length will vary by database vendor.
+
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models.adoc
new file mode 100644
index 0000000..37929da
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models.adoc
@@ -0,0 +1,631 @@
+[[_ugfun_programming-model_view-models]]
+= View Models
+
+: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/
+
+
+
+
+NOTE: FIXME - move the stuff from ugbtb here
+
+NOTE: FIXME - deprecate the @ViewModel stuff, emphasise using JAXB only
+
+
+
+
+[[__ugfun_building-blocks_view-models_typical-implementation]]
+== Typical Implementation
+
+Apache Isis offers several ways to implement view models, but the most flexible/powerful is to annotate the class using JAXB annotations.
+For example:
+
+[source,java]
+----
+@XmlRootElement(name = "invoiceRun")    // <1>
+@XmlType(
+        propOrder = {                   // <2>
+            ...
+        }
+)
+public class InvoiceRun {
+    ...
+}
+----
+<1> The JAXB `@XmlRootElement` annotation indicates this is a view model to Apache Isis, which then uses JAXB to serialize the state of the view model between interactions
+<2> All properties of the view model must be listed using the `XmlType#propOrder` attribute.
+
+Use JAXB elements such as `@XmlElement` for properties and the combination of `@XmlElementWrapper` and `@XmlElement` for collections.
+Properties can be ignored (for serialization) using `@XmlTransient`.
+
+
+''''
+''''
+
+[[_ugbtb_view-models_jaxb]]
+== JAXB-annotated View Models/DTOs
+
+As noted in the xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_view-models[introduction], view models can also be defined using JAXB annotations.
+The serialized form of these view models is therefore XML, which also enables these view models
+to act as DTOs.
+
+In case it's not obvious, these DTOs are still usable as "regular" view models; they will render in the xref:../ugvw/ugvw.adoc#[Wicket viewer] just like any other.
+In fact, these JAXB-annotated view models are in many regards the most powerful of all the various ways of writing view models:
+
+* their entire state (collections as well as properties) is automatically managed from interaction to interaction. +
++
+In contrast, using xref:../rgant/rgant.adoc#_rgant-ViewModel[`@ViewModel`] (or its xref:../rgant/rgant.adoc#_rgant-DomainObject_nature[`@DomainObject#nature()`] equivalent) will only manage the state of properties, but not collections.
+And if using the xref:../rgcms/rgcms.adoc#_rgcms_classes_super_ViewModel[`ViewModel`] interface, then the programmer must write all the state management (lots of boilerplate).
+
+* JAXB-annotated view models are "in effect" editable.
+
+The examples in this section uses the DTO for `ToDoItem`, taken from the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp].
+This DTO is defined as follows:
+
+[source,java]
+----
+package todoapp.app.viewmodels.todoitem.v1;                         // <1>
+@XmlRootElement(name = "toDoItemDto")                               // <2>
+@XmlType(
+        propOrder = {                                               // <3>
+            "majorVersion", "minorVersion",
+            "description", "category", ...
+            "toDoItem", "similarItems"
+        }
+)
+@DomainObjectLayout(
+        titleUiEvent = TitleUiEvent.Doop.class                      // <4>
+)
+public class ToDoItemV1_1 implements Dto {                          // <5>
+    @XmlElement(required = true, defaultValue = "1")                // <6>
+    public final String getMajorVersion() { return "1"; }
+    @XmlElement(required = true, defaultValue = "1")                // <7>
+    public String getMinorVersion() { return "1"; }
+
+    @XmlElement(required = true)                                    // <8>
+    @Getter @Setter
+    protected String description;
+    @XmlElement(required = true)
+    @Getter @Setter
+    protected String category;
+    ...
+
+    @Getter @Setter                                                 // <9>
+    protected ToDoItem toDoItem;
+    @XmlElementWrapper                                              // <10>
+    @XmlElement(name = "todoItem")
+    @Getter @Setter
+    protected List<ToDoItem> similarItems = Lists.newArrayList();
+}
+----
+<1> package name encodes major version; see discussion on xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_versioning[versioning]
+<2> identifies this class as a view model and defines the root element for JAXB serialization
+<3> all properties in the class must be listed; (they can be ignored using `@XmlTransient`)
+<4> demonstrating use of UI events for a subscriber to provide the DTO's title; see xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_titleUiEvent[`@DomainObjectLayout#titleUiEvent()`].
+<5> class name encodes (major and) minor version; see discussion on xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_versioning[versioning]
+<6> again, see discussion on xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_versioning[versioning]
+<7> again, see discussion on xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_versioning[versioning]
+<8> simple scalar properties
+<9> reference to a persistent entity; discussed xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_referencing-domain-entities[below]
+<10> reference to a collection of persistent entities; again discussed xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_referencing-domain-entities[below]
+
+
+
+[[__ugbtb_view-models_jaxb_referencing-domain-entities]]
+=== Referencing Domain Entities
+
+It's quite common for view models to be "backed by" (be projections of) some underlying domain entity.
+The `ToDoItemDto` we've been using as the example in this section is an example: there is an underlying `ToDoItem` entity.
+
+It wouldn't make sense to serialize out the state of a persistent entity: the point of a DTO is to act as a facade on top of the entity so that the implementation details (of the entity's structure) don't leak out to the consumer.
+However, the identity of the underlying entity can be well defined; Apache Isis defines the xref:../rgcms/rgcms.adoc#_rgcms_schema-common[Common schema] which defines the `<oid-dto>` element (and corresponding `OidDto` class): the object's type and its identifier.
+This is basically a formal XML equivalent to the `Bookmark` object obtained from the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`].
+
+There is only one requirement to make this work: every referenced domain entity must be annotated with xref:../rgant/rgant.adoc#_rgant-XmlJavaTypeAdapter[`@XmlJavaTypeAdapter`], specifying the framework-provided `PersistentEntityAdapter.class`.
+This class is similar to the `BookmarkService`: it knows how to create an `OidDto` from an object reference.
+
+Thus, in our view model we can legitimately write:
+
+[source,java]
+----
+package todoapp.app.viewmodels.todoitem.v1;
+...
+public class ToDoItemV1_1 implements Dto {
+    ...
+    @Getter @Setter
+    protected ToDoItem toDoItem;
+}
+----
+
+All we need to do is remember to add that `@XmlJavaTypeAdapter` annotation to the referenced entity:
+
+[source,java]
+----
+@XmlJavaTypeAdapter(PersistentEntityAdapter.class)
+public class ToDoItem ...  {
+    ...
+}
+----
+
+
+It's also possible for a DTO to hold collections of objects.
+These can be of any type, either simple properties, or references to other objects.
+The only bit of boilerplate that is required is the `@XmlElementWrapper` annotation.
+This instructs JAXB to create an XML element (based on the field name) to contain each of the elements.
+(If this is omitted then the contents of the collection are at the same level as the properties; almost certainly not what is required).
+
+For example, the DTO also contains:
+
+[source,java]
+----
+package todoapp.app.viewmodels.todoitem.v1;
+...
+public class ToDoItemV1_1 implements Dto {
+    ...
+    @XmlElementWrapper
+    @XmlElement(name = "todoItem")
+    @Getter @Setter
+    protected List<ToDoItem> similarItems = Lists.newArrayList();
+}
+----
+
+
+There's nothing to prevent a JAXB DTO from containing rich graphs of data, parent containing children containing children.
+Be aware though that all of this state will become the DTO's memento, ultimately converted into a URL-safe form, by way of the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UrlEncodingService[`UrlEncodingService`].
+
+There are limits to the lengths of URLs, however.
+Therefore the DTO should not include state that can easily be derived from other information.
+If the URL does exceed limits, then provide a custom implementation of xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UrlEncodingService[`UrlEncodingService`] to handle the memento string in some other fashion (eg substituting it with a GUID, with the memento cached somehow on the server).
+
+
+
+
+
+[[__ugbtb_view-models_jaxb_versioning]]
+=== Versioning
+
+The whole point of using DTOs (in Apache Isis, at least) is to define a formal contact between two inter-operating but independent applications.
+Since the only thing we can predicate about the future with any certainty is that it one or both of these applications will change, we should version DTOs from the get-go.
+This allows us to make changes going forward without unnecessarily breaking existing consumers of the data.
+
+[NOTE]
+====
+There are several ways that versioning might be accomplished; we base our guidelines on this link:http://www.xfront.com/Versioning.pdf[article] taken from Roger Costello's blog, well worth a read.
+====
+
+We can distinguish two types of changes:
+
+* backwardly compatible changes
+* breaking changes.
+
+We can immediately say that the XSD namespace should change only when there is a major/breaking change, if following link:http://semver.org[semantic versioning] that means when we bump the major version number v1, v2, etc.
+
+XML namespaces correspond (when using JAXB) to Java packages.
+We should therefore place our DTOs in a package that contains only the major number; this package will eventually contain a range of DTOs that are intended to be backwardly compatible with one another.
+The package should also have a `package-info.java`; it is this that declares the XSD namespace:
+
+[source,java]
+----
+@javax.xml.bind.annotation.XmlSchema(
+        namespace = "http://viewmodels.app.todoapp/todoitem/v1/Dto.xsd",        // <1>
+        xmlns = {
+                @javax.xml.bind.annotation.XmlNs(
+                        namespaceURI = "http://isis.apache.org/schema/common",
+                        prefix = "com"
+                )
+        },
+        elementFormDefault = javax.xml.bind.annotation.XmlNsForm.QUALIFIED
+)
+package todoapp.app.viewmodels.todoitem.v1;                                     // <2>
+----
+<1> the namespace URI, used by the DTO residing in this package.
+<2> the package in which the DTO resides.  Note that this contains only the major version.
+
+Although there is no requirement for the namespace URI to correspond to a physical URL, it should be unique.
+This usually means including a company domain name within the string.
+
+As noted above, this package will contain multiple DTO classes all with the same namespace; these represent a set of minor versions of the DTO, each subsequent one intended to be backwardly compatible with the previous.
+Since these DTO classes will all be in the same package (as per the xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_using-packages-to-version[advice above]), the class should therefore include the minor version name:
+
+[source,java]
+----
+package todoapp.app.viewmodels.todoitem.v1;     // <1>
+...
+public class ToDoItemV1_1 implements Dto {      // <2>
+    ...
+}
+----
+<1> package contains the major version only
+<2> DTO class contains the (major and) minor version
+
+
+We also recommend that each DTO instance should also specify the version of the XSD schema that it is logically compatible with.
+Probably most consumers will not persist the DTOs; they will be processed and then discarded.
+However, it would be wrong to assume that is the case in all cases; some consumers might choose to persist the DTO (eg for replay at some later state).
+
+Thus:
+
+[source,java]
+----
+public class ToDoItemV1_1 implements Dto {
+    @XmlElement(required = true, defaultValue = "1")
+    public final String getMajorVersion() { return "1"; }   // <1>
+    @XmlElement(required = true, defaultValue = "1")
+    public String getMinorVersion() { return "1"; }         // <2>
+    ...
+}
+----
+<1> returns the major version (in sync with the package)
+<2> returns the minor version (in sync with the class name)
+
+These methods always return a hard-coded literal.
+Any instances serialized from these classes will implicitly "declare" the (major and) minor version of the schema with which they are compatible.
+If a consumer has a minimum version that it requires, it can therefore inspect the XML instance itself to determine if it is able to consume said XML.
+
+If a new (minor) version of a DTO is required, then we recommend copying-and-pasting the previous version, eg:
+
+[source,java]
+----
+public class ToDoItemV1_2 implements Dto {
+    @XmlElement(required = true, defaultValue = "1")
+    public final String getMajorVersion() { return "1"; }
+    @XmlElement(required = true, defaultValue = "2")
+    public String getMinorVersion() { return "2"; }
+    ...
+}
+----
+
+Obviously, only changes made must be backward compatible, eg new members must be optional.
+
+Alternatively, you might also consider simply editing the source file, ie renaming the class and bumping up the value returned by `getMinorVersion()`.
+
+We also _don't_ recommend using inheritance (ie `ToDoItemV1_2` should not inherit from `ToDoItemV1_1`; this creates unnecessary complexity downstream if generating XSDs and DTOs for the downstream consumer.
+
+
+[[__ugbtb_view-models_jaxb_generating-xsds-and-dtos]]
+=== Generating XSDs and DTOs
+
+In the section xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_referencing-domain-entities[above] it was explained how a view model DTO can transparent reference any "backing" entities; these references are converted to internal object identifiers.
+
+However, if the consumer of the XML is another Java process (eg running within an Apache Camel route), then you might be tempted/expect to be able to use the same DTO within that Java process.
+After a little thought though you'll realize that (duh!) of course you cannot; the consumer runs in a different process space, and will not have references to those containing entities.
+
+There are therefore two options:
+
+* either choose not to have the view model DTO reference any persistent entities, and simply limit the DTO to simple scalars. +
++
+Such a DTO will then be usable in both the Apache Isis app (to generate the original XML) and in the consumer.
+The xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`] can be used to obtain the object identifiers
+
+* alternatively, generate a different DTO for the consumer from the XSD of the view model DTO.
+
+The (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] uses the second approach; generating the XSD and consumer's DTO is mostly just boilerplate `pom.xml` file.
+In the todoapp this can be found in the `todoapp-xsd` Maven module, whose `pom.xml` is structured as two profiles:
+
+[source,xml]
+----
+<project ... >
+    <artifactId>todoapp-xsd</artifactId>
+    <dependencies>
+        <dependency>
+            <groupId>${project.groupId}</groupId>
+            <artifactId>todoapp-app</artifactId>
+        </dependency>
+    </dependencies>
+    <profiles>
+        <profile>
+            <id>isis-xsd</id>
+            <activation>
+                <property>
+                    <name>!skip.isis-xsd</name>
+                </property>
+            </activation>
+            ...
+        </profile>
+        <profile>
+            <id>xjc</id>
+            <activation>
+                <property>
+                    <name>!skip.xjc</name>
+                </property>
+            </activation>
+            ...
+        </profile>
+    </profiles>
+</project>
+----
+
+The `isis-xsd` profile generates the XSD using the xref:../rgmvn/rgmvn.adoc#_rgmvn_xsd[`xsd` goal] of Isis' maven plugin:
+
+[source,xml]
+----
+<build>
+    <plugins>
+        <plugin>
+            <groupId>org.apache.isis.tool</groupId>
+            <artifactId>isis-maven-plugin</artifactId>
+            <version>${isis.version}</version>
+            <configuration>
+                <appManifest>todoapp.dom.ToDoAppDomManifest</appManifest>
+                <jaxbClasses>
+                    <jaxbClass>todoapp.app.viewmodels.todoitem.v1.ToDoItemV1_1</jaxbClass>
+                </jaxbClasses>
+                <separate>false</separate>
+                <commonSchemas>false</commonSchemas>
+            </configuration>
+            <dependencies>
+                <dependency>
+                    <groupId>${project.groupId}</groupId>
+                    <artifactId>todoapp-dom</artifactId>
+                    <version>${project.version}</version>
+                </dependency>
+                <dependency>
+                    <groupId>com.google.guava</groupId>
+                    <artifactId>guava</artifactId>
+                    <version>16.0.1</version>
+                </dependency>
+            </dependencies>
+            <executions>
+                <execution>
+                    <phase>generate-sources</phase>
+                    <goals>
+                        <goal>xsd</goal>
+                    </goals>
+                </execution>
+            </executions>
+        </plugin>
+        <plugin>
+            <artifactId>maven-assembly-plugin</artifactId>
+            <version>2.5.3</version>
+            <configuration>
+                <descriptor>src/assembly/dep.xml</descriptor>
+            </configuration>
+            <executions>
+                <execution>
+                    <id>create-archive</id>
+                    <phase>package</phase>
+                    <goals>
+                        <goal>single</goal>
+                    </goals>
+                </execution>
+            </executions>
+        </plugin>
+    </plugins>
+</build>
+----
+
+The `todoapp.dom.ToDoAppDomManifest` is a cut-down version of the app manifest that identifies only the `dom` domain services.
+
+The `xjc` profile, meanwhile, uses the `maven-jaxb2-plugin` (a wrapper around the `schemagen` JDK tool) to generate a DTO from the XSD generated by the preceding profile:
+
+[source,xml]
+----
+<build>
+    <plugins>
+        <plugin>
+            <groupId>org.jvnet.jaxb2.maven2</groupId>
+            <artifactId>maven-jaxb2-plugin</artifactId>
+            <version>0.12.3</version>
+            <executions>
+                <execution>
+                    <id>xjc-generate</id>
+                    <phase>generate-sources</phase>
+                    <goals>
+                        <goal>generate</goal>
+                    </goals>
+                </execution>
+            </executions>
+            <configuration>
+                <removeOldOutput>true</removeOldOutput>
+                <schemaDirectory>
+                    target/generated-resources/isis-xsd/viewmodels.app.todoapp
+                </schemaDirectory>
+                <schemaIncludes>
+                    <schemaInclude>todoitem/v1/Dto.xsd</schemaInclude>
+                </schemaIncludes>
+                <bindingDirectory>src/main/resources</bindingDirectory>
+                <bindingIncludes>
+                    <bindingInclude>binding.xml</bindingInclude>
+                </bindingIncludes>
+                <catalog>src/main/resources/catalog.xml</catalog>
+            </configuration>
+        </plugin>
+        <plugin>
+            <groupId>org.codehaus.mojo</groupId>
+            <artifactId>build-helper-maven-plugin</artifactId>
+            <version>1.9.1</version>
+            <executions>
+                <execution>
+                    <id>add-source</id>
+                    <phase>generate-sources</phase>
+                    <goals>
+                        <goal>add-source</goal>
+                    </goals>
+                    <configuration>
+                    <sources>
+                        <source>target/generated-sources/xjc</source>
+                    </sources>
+                    </configuration>
+                </execution>
+            </executions>
+        </plugin>
+    </plugins>
+</build>
+----
+
+
+''''
+''''
+
+== (Non-JAXB) View Models
+
+NOTE: FIXME - consider this as deprecated
+
+This section describes how to implement view models.
+
+Fundamentally all view models' state is serialized into
+a string memento; this memento is then held by the client (browser) in the form of a URL.  As you might imagine, this
+URL can become quite long, but Apache Isis offers a mechanism (the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UrlEncodingService[`UrlEncodingService`]) if it exceeds the maximum length for a URL
+(2083 characters).  Also, of course, this string memento must only contain characters that it is valid for use within
+a URL.
+
+While the underlying technique is the same irrespective of use case, the programming model provides various ways of
+defining a view model so that the original intent is not lost.  They are:
+
+.View model programming model
+[cols="1a,4a,2a", options="header"]
+|===
+
+| Use case
+| Code
+| Description
+
+
+| External entity
+|[source,java]
+----
+@DomainObject(nature=Nature.EXTERNAL_ENTITY)
+public class CustomerRecordOnSAP { ... }
+----
+|Annotated with xref:../rgant/rgant.adoc#_rgant-DomainObject_nature[`@DomainObject#nature()`] and a nature of `EXTERNAL_ENTITY`, with memento derived automatically from the properties of the domain object.  Collections are ignored, as are any properties annotated as xref:../rgant/rgant.adoc#_rgant-Property_notPersisted[not persisted].
+
+| In-memory entity
+|[source,java]
+----
+@DomainObject(nature=Nature.INMEMORY_ENTITY)
+public class Log4JAppender { ... }
+----
+|As preceding, but using a nature of `INMEMORY_ENTITY`.
+
+|Application view model
+|[source,java]
+----
+@DomainObject(nature=Nature.VIEW_MODEL)
+public class Dashboard { ... }
+----
+|As preceding, but using a nature of `VIEW_MODEL`.
+
+|Application view model
+|
+[source,java]
+----
+@ViewModel
+public class Dashboard { ... }
+----
+
+|Annotated with xref:../rgant/rgant.adoc#_rgant-ViewModel[`@ViewModel`] annotation (effectively just an alias)' memento is as preceding: from "persisted" properties, collections ignored
+
+|Application view model
+|
+[source,java]
+----
+public class ExcelUploadManager implements ViewModel {
+  public String viewModelMemento() { ... }
+  public void viewModelInit(String memento) { ... }
+}
+|Implement xref:../rgcms/rgcms.adoc#_rgcms_classes_super_ViewModel[`ViewModel`] interface.  The memento is as defined by the
+interface's methods: the programmer has full control (but also full responsibility) for the string memento.
+
+|DTO
+|
+[source,java]
+----
+@XmlRootElement("customer")
+public class CustomerDto { ... }
+----
+|Annotate using JAXB xref:../rgant/rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`] annotation.  Memento
+derived automatically by serializing the XML graph as implied by the JAXB annotations.  Note that (unlike `@ViewModel`
+et al) this state _can_ include collections.
+|===
+
+JAXB-annotated DTOs are discussed in more detail immediately xref:rg.adoc#_ugbtb_view-models_jaxb[below].
+
+
+
+''''
+''''
+
+
+
+This section describes how to implement view models.
+
+Fundamentally all view models' state is serialized into
+a string memento; this memento is then held by the client (browser) in the form of a URL.  As you might imagine, this
+URL can become quite long, but Apache Isis offers a mechanism (the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UrlEncodingService[`UrlEncodingService`]) if it exceeds the maximum length for a URL
+(2083 characters).  Also, of course, this string memento must only contain characters that it is valid for use within
+a URL.
+
+While the underlying technique is the same irrespective of use case, the programming model provides various ways of
+defining a view model so that the original intent is not lost.  They are:
+
+.View model programming model
+[cols="1a,4a,2a", options="header"]
+|===
+
+| Use case
+| Code
+| Description
+
+
+| External entity
+|[source,java]
+----
+@DomainObject(nature=Nature.EXTERNAL_ENTITY)
+public class CustomerRecordOnSAP { ... }
+----
+|Annotated with xref:../rgant/rgant.adoc#_rgant-DomainObject_nature[`@DomainObject#nature()`] and a nature of `EXTERNAL_ENTITY`, with memento derived automatically from the properties of the domain object.  Collections are ignored, as are any properties annotated as xref:../rgant/rgant.adoc#_rgant-Property_notPersisted[not persisted].
+
+| In-memory entity
+|[source,java]
+----
+@DomainObject(nature=Nature.INMEMORY_ENTITY)
+public class Log4JAppender { ... }
+----
+|As preceding, but using a nature of `INMEMORY_ENTITY`.
+
+|Application view model
+|[source,java]
+----
+@DomainObject(nature=Nature.VIEW_MODEL)
+public class Dashboard { ... }
+----
+|As preceding, but using a nature of `VIEW_MODEL`.
+
+|Application view model
+|
+[source,java]
+----
+@ViewModel
+public class Dashboard { ... }
+----
+
+|Annotated with xref:../rgant/rgant.adoc#_rgant-ViewModel[`@ViewModel`] annotation (effectively just an alias)' memento is as preceding: from "persisted" properties, collections ignored
+
+|Application view model
+|
+[source,java]
+----
+public class ExcelUploadManager implements ViewModel {
+  public String viewModelMemento() { ... }
+  public void viewModelInit(String memento) { ... }
+}
+|Implement xref:../rgcms/rgcms.adoc#_rgcms_classes_super_ViewModel[`ViewModel`] interface.  The memento is as defined by the
+interface's methods: the programmer has full control (but also full responsibility) for the string memento.
+
+|DTO
+|
+[source,java]
+----
+@XmlRootElement("customer")
+public class CustomerDto { ... }
+----
+|Annotate using JAXB xref:../rgant/rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`] annotation.  Memento
+derived automatically by serializing the XML graph as implied by the JAXB annotations.  Note that (unlike `@ViewModel`
+et al) this state _can_ include collections.
+|===
+
+JAXB-annotated DTOs are discussed in more detail immediately xref:rg.adoc#_ugbtb_view-models_jaxb[below].
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/building-blocks/types-of-domain-object.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/building-blocks/types-of-domain-object.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/building-blocks/types-of-domain-object.png
deleted file mode 100644
index 1ec6e18..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/building-blocks/types-of-domain-object.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/building-blocks/types-of-domain-object.pptx
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/building-blocks/types-of-domain-object.pptx b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/building-blocks/types-of-domain-object.pptx
deleted file mode 100644
index c0be2a5..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/building-blocks/types-of-domain-object.pptx and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/images/how-tos/domain-services/hexagonal-architecture-addons.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/how-tos/domain-services/hexagonal-architecture-addons.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/how-tos/domain-services/hexagonal-architecture-addons.png
deleted file mode 100644
index af32db1..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/how-tos/domain-services/hexagonal-architecture-addons.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/images/how-tos/tips-n-tricks/action-semantics-are-you-sure.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/how-tos/tips-n-tricks/action-semantics-are-you-sure.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/how-tos/tips-n-tricks/action-semantics-are-you-sure.png
deleted file mode 100644
index f0cf269..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/how-tos/tips-n-tricks/action-semantics-are-you-sure.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/images/how-tos/tips-n-tricks/are-you-sure-happy-case.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/how-tos/tips-n-tricks/are-you-sure-happy-case.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/how-tos/tips-n-tricks/are-you-sure-happy-case.png
deleted file mode 100644
index 1981c09..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/how-tos/tips-n-tricks/are-you-sure-happy-case.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/images/how-tos/tips-n-tricks/are-you-sure-sad-case.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/how-tos/tips-n-tricks/are-you-sure-sad-case.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/how-tos/tips-n-tricks/are-you-sure-sad-case.png
deleted file mode 100644
index 6182447..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/how-tos/tips-n-tricks/are-you-sure-sad-case.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/images/how-tos/tips-n-tricks/are-you-sure.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/how-tos/tips-n-tricks/are-you-sure.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/how-tos/tips-n-tricks/are-you-sure.png
deleted file mode 100644
index e1a76fe..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/how-tos/tips-n-tricks/are-you-sure.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/ugfun.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/ugfun.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/ugfun.adoc
index 432c473..b548183 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/ugfun.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/ugfun.adoc
@@ -47,11 +47,12 @@ The remaining guides are:
 
 
 include::_ugfun_core-concepts.adoc[leveloffset=+1]
-include::_ugfun_getting-started.adoc[leveloffset=+1]
 
-include::_ugfun_domain-class-ontology.adoc[leveloffset=+1]
+include::_ugfun_building-blocks.adoc[leveloffset=+1]
+
+include::_ugfun_getting-started.adoc[leveloffset=+1]
 
-include::_ugfun_class-structure.adoc[leveloffset=+1]
+include::_ugfun_programming-model.adoc[leveloffset=+1]
 include::_ugfun_ui-hints.adoc[leveloffset=+1]
 
 include::_ugfun_crud.adoc[leveloffset=+1]
@@ -60,3 +61,5 @@ include::_ugfun_business-rules.adoc[leveloffset=+1]
 
 include::_ugfun_drop-downs-and-defaults.adoc[leveloffset=+1]
 
+include::_ugfun_available-domain-services.adoc[leveloffset=+1]
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips.adoc
index de70245..1efd665 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips.adoc
@@ -24,6 +24,7 @@ See also hints-n-tips chapters in the:
 
 include::_ugodn_hints-and-tips_overriding-jdo-annotations.adoc[leveloffset=+1]
 include::_ugodn_hints-and-tips_handling-mandatory-properties-in-subtypes.adoc[leveloffset=+1]
+include::_ugodn_hints-and-tips_mapping-to-a-view.adoc[leveloffset=+1]
 
 include::_ugodn_hints-and-tips_subtype-entity-not-fully-populated.adoc[leveloffset=+1]
 include::_ugodn_hints-and-tips_java8.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_mapping-to-a-view.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_mapping-to-a-view.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_mapping-to-a-view.adoc
new file mode 100644
index 0000000..a50c2a0
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_mapping-to-a-view.adoc
@@ -0,0 +1,9 @@
+[[_ugodn_hints-and-tips_mapping-to-a-view]]
+= Mapping to a View
+: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/
+
+
+NOTE: FIXME - as per Estatio's Invoice stuff
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations.adoc
index 3a61eb3..ef4e697 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations.adoc
@@ -7,370 +7,24 @@
 
 
 The representations defined by the RO spec are very rich and enable complex client-side applications to be built.
-However, their sophistication can be an impediment to their use if one wishes to write a simple app using third-party
-components that expect to consume much simpler representations.  Examples of such tools are
+However, their sophistication can be an impediment to their use if one wishes to write a simple app using third-party components that expect to consume much simpler representations.
+Examples of such tools are
 link:http://angular-ui.github.io/bootstrap/[Angular Bootstrap],
 link:http://vitalets.github.io/angular-xeditable/[Angular XEditable],
 link:https://github.com/mgcrea/angular-strap[Angular Strap].
 
 
-As of `1.11.0`, Apache Isis provides support for its own simplified representation for the most commonly-used
-representations.  This is implemented using the `ContentNegotiationService` described in the
+As of `1.11.0`, Apache Isis provides support for its own simplified representation for the most commonly-used representations.
+This is implemented using the `ContentNegotiationService` described in the
 xref:../ugvro/ugvro.adoc#_ugvro_architecture[architecture] chapter.
 
 
 
-[[__ugvro_simplified-representations_apache-isis-profile]]
-== The Apache Isis "Profile"
-
-The RO spec uses the standard `Accept` header for content negotiation, and defines its own "profile" for the standard
-representations; these take the form:
-
-[source]
-----
-Accept: application/json;profile="urn:org.restfulobjects:repr-types/xxx"
-----
-
-where "xxx" varies by resource.  The detail can be found in section 2.4.1 of the RO spec.
-
-The Apache Isis viewer also defines its own "Isis" profile which enables the client to request simplified
-representations for the most frequently accessed resources.  This is done by specifying an `Accept` header of:
-
-[source]
-----
-Accept: application/json;profile="urn:org.apache.isis/v1"
-----
-
-Not every resource supports this header, but the most commonly accessed ones do.  In each case the server will set the
-`Content-Type` header so that the client knows how to process the representation.
-
-The link:https://www.youtube.com/watch?v=HMSqapQDY_4[screencast] demonstrates the feature.
-
-
-
-The sections below explain in a little more detail what is returned when this profile is activated.
-
-
-[[__ugvro_simplified-representations_domain-object]]
-== Domain Object
-
-If a domain object resource (section 14) is accessed with the Apache Isis profile, the resultant representation is a
-JSON object with simple key/value pairs for each property.
-
-The contents of any collections are also eagerly returned, consisting of an array of elements of each referenced
-object.  Each such element contains key/value pairs of each property (in other words, a grid of data is returned).
-Each element also has a special `$$href` property (so that the client can easily navigate to a resource for that
-object) and a `$$title` property (to use as a label, eg the hyperlink text).
-
-In addition, the representation defined by the RO spec is also included, under a special `$$ro` property.
-
-For example, using the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp], accessing
-this resource:
-
-[source]
-----
-http://localhost:8080/restful/objects/TODO/45
-----
-
-with an `Accept` request header of:
-
-[source]
-----
-Accept: application/json;profile="urn:org.apache.isis/v1"
-----
-
-returns the following representation:
-
-[source]
-----
-{
-  "$$href" : "http://localhost:8080/restful/objects/TODO/45",       // <1>
-  "$$instanceId" : "45",                                            // <2>
-  "$$title" : "Buy bread due by 2015-12-04",                        // <3>
-  "description" : "Buy bread",                                      // <4>
-  "category" : "Domestic",
-  "subcategory" : "Shopping",
-  "complete" : false,
-  "atPath" : "/users/sven",
-  ...
-  "similarTo" : [ {                                                 // <5>
-    "$$href" : "http://localhost:8080/restful/objects/TODO/46",
-    "$$instanceId" : "46",
-    "$$title" : "Buy milk due by 2015-12-04",
-    "description" : "Buy milk",
-    "category" : "Domestic",
-    ...
-  }, {
-    "$$href" : "http://localhost:8080/restful/objects/TODO/47",
-    "$$instanceId" : "47",
-    "$$title" : "Buy stamps due by 2015-12-04",
-    "description" : "Buy stamps",
-    "category" : "Domestic",
-    ...
-  },
-     ...
-  } ],
-  "dependencies" : [ ],
-  "$$ro" : {                                                        // <6>
-    "links" : [ ... ],
-    "extensions" : { ... },
-    "title" : "Buy bread due by 2015-12-04",
-    "domainType" : "TODO",
-    "instanceId" : "45",
-    "members" : { ... }
-  }
-}
-----
-<1> hyperlink to the representation
-<2> instance id of the domain object (unique within its type)
-<3> title of the domain object
-<4> all the properties of the domain object (to which the caller has access), as key/value pairs
-<5> contents of each collection
-<6> special `$$ro` json-prop, being the normal RO Spec representation for this object
-
-with a `Content-Type` header:
-
-[source]
-----
-Content-Type: application/json;
-              profile="urn:org.apache.isis/v1";repr-type="object"
-----
-
-
-[[__ugvro_simplified-representations_object-collection]]
-== Domain Object Collection
-
-If a domain object collection (section 17) is accessed with this profile, then the resultant representation is as
-an array of elements of key/value for each referenced object, and again each element the containing the key/value
-pairs of the properties of that object (a grid, again). +
-
-In addition, the representation defined by the RO spec is also included, as a special object with a single `$$ro`
-property.
-
-For example, using the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp], accessing
-this resource:
-
-[source]
-----
-http://localhost:8080/restful/objects/TODO/45/collections/similarTo
-----
-
-with an `Accept` request header of:
-
-[source]
-----
-Accept: application/json;profile="urn:org.apache.isis/v1"
-----
-
-returns the following representation:
-
-[source]
-----
-[                                                                   // <1>
-{
-  "$$href" : "http://localhost:8080/restful/objects/TODO/46",       // <2>
-  "$$instanceId" : "46",                                            // <3>
-  "$$title" : "Buy milk due by 2015-12-04",                         // <4>
-  "description" : "Buy milk",                                       // <5>
-  "category" : "Domestic",
-  ...
-}, {
-  "$$href" : "http://localhost:8080/restful/objects/TODO/47",
-  "$$title" : "Buy stamps due by 2015-12-04",
-  "description" : "Buy stamps",
-  "category" : "Domestic",
-  ...
-}, {
-  "$$href" : "http://localhost:8080/restful/objects/TODO/48",
-  "$$title" : "Mow lawn due by 2015-12-10",
-  "description" : "Mow lawn",
-  "category" : "Domestic",
-  ...
-},
-...
-, {
-  "$$ro" : {                                                        // <6>
-    "id" : "similarTo",
-    "memberType" : "collection",
-    "links" : [ ... ],
-    "extensions" : { ... },
-    "value" : [ ... ]
-  }
-}
-]
-----
-<1> returns a JSON array, not a JSON object
-<2> hyperlink to the representation
-<3> instance id of the domain object (unique within its type)
-<4> title of the domain object
-<5> all the properties of the domain object (to which the caller has access), as key/value pairs
-<6> last element is a special object with a single `$$ro` json-prop, being the normal RO Spec representation for this object
-
-with a `Content-Type` header:
-
-[source]
-----
-Content-Type: application/json;profile="urn:org.apache.isis/v1";repr-type="object-collection"
-----
-
-
-[[__ugvro_simplified-representations_action-invocation]]
-== Action Invocation
-
-When an action is invoked, it can return a domain object, a list, a scalar, or return nothing.
-
-=== Returning an Object
-
-If the action returned an object, then the domain object representation described
-xref:../ugvro/ugvro.adoc#__ugvro_simplified-representations_domain-object[above] is returned.
-
-For example, using the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp], accessing
-this resource:
-
-[source]
-----
-http://localhost:8080/restful/objects/TODO/45/actions/updateCost/invoke
-----
-
-with an `Accept` request header of:
-
-[source]
-----
-Accept: application/json;profile="urn:org.apache.isis/v1"
-----
-
-returns the following representation:
-
-[source]
-----
-
-{
-  "$$href" : "http://localhost:8080/restful/objects/TODO/45",
-  "$$instanceId" : "45",
-  "$$title" : "Buy bread due by 2015-12-04",
-  "description" : "Buy bread",
-  "category" : "Domestic",
-  "subcategory" : "Shopping",
-  "complete" : false,
-  ...
-  "similarTo" : [ ... ]
-  ...
-  "$$ro" : { ... }
-}
-----
-
-with a `Content-Type` of:
-
-[source]
-----
-Content-Type: application/json;profile="urn:org.apache.isis/v1";repr-type="object"
-----
-
-\... in other words no different to a representation obtained of the returned domain object directly.
-
-
-=== Returning a List
-
-On the other hand if the action returned a list (a "standalone" collection, then an array representation is returned.
-This is very similar to that returned by a
-xref:../ugvro/ugvro.adoc#__ugvro_simplified-representations_object-collection[(parented) object collection], though with a
-slightly different `Content-Type` to distinguish.
-
-For example, using the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp], accessing
-this resource:
-
-[source]
-----
-http://localhost:8080/restful/services/ToDoItems/actions/notYetComplete/invoke
-----
-
-with an `Accept` request header of:
-
-[source]
-----
-Accept: application/json;profile="urn:org.apache.isis/v1"
-----
-
-returns the following representation:
-
-[source]
-----
-[ {
-  "$$href" : "http://localhost:8080/restful/objects/TODO/45",
-  "$$instanceId" : "45",
-  "$$title" : "Buy bread due by 2015-12-04",
-  "description" : "Buy bread",
-  "category" : "Domestic",
-  ...
-}, {
-  "$$href" : "http://localhost:8080/restful/objects/TODO/46",
-  "$$instanceId" : "46",
-  "$$title" : "Buy milk due by 2015-12-04",
-  "description" : "Buy milk",
-  "category" : "Domestic",
-  ...
-},
-...
-, {
-  "$$ro" : {
-    "links" : [ ... ]
-    "resulttype" : "list",
-    "result" : { ... }
-      "value" : [ ... ],
-      "links" : [ ... ],
-      "extensions" : { }
-    }
-  }
-} ]
-----
-
-with a `Content-Type` header:
-
-[source]
-----
-Content-Type: application/json;profile="urn:org.apache.isis/v1";repr-type="list"
-----
-
-=== Returning Scalar/Nothing
-
-Note that actions returning scalar values or nothing (which includes `void` actions) are not supported; for these the
-regular RO spec representation will be returned.
-
-
-[[__ugvro_simplified-representations_other-representations]]
-== Supporting other Representations
-
-Sometimes though you may want to extend or change the representations generated.  This might be because you want to
-write a RESTful client that uses a particular library (say a Javascript library or web components) that can only handle representations in a certain form.
-
-Or, you might want to have Apache Isis generate representations according to some other "standard", of which there are
-many:
-
-* Mike Kelly's http://stateless.co/hal_specification.html[HAL] specification
-* Mike Amundsen's http://amundsen.com/media-types/collection/[Collection+JSON] specification
-* Kevin Swiber's https://github.com/kevinswiber/siren[Siren] specification
-* Steve Klabnik's http://jsonapi.org/[JSON API] specification
-* Gregg Cainus' https://github.com/cainus/hyper-json-spec[Hyper+JSON] specification
-* the W3C's https://www.w3.org/TR/json-ld/[JSON-LD] specification
-* Markus Lanthaler's http://www.markus-lanthaler.com/hydra/[Hydra] specification.
-
-A good discussion about the relative merits of several of these different hypermedia formats can be found https://groups.google.com/forum/#!msg/api-craft/NgjzQYVOE4s/EAB2jxtU_TMJ[here].
-
-Or, of course, you may have your own internal specification that you wish to use.
-
-Supporting any of these alternative representations can be achieved by providing a suitable implementation of
-`ContentNegotiationService`.  The existing implementations (eg `ContentNegotiationServiceSimplified`) can be used as a
-starting point.
-
-[NOTE]
-====
-These will, admittedly, need to access the internal APIs for the Apache Isis metamodel, and you should be aware that
-these are not formal API; they may change over time.  That said, they are very stable and have not changed
-significantly over the last few years.
-====
-
-
-
-include::__ugvro_simplified-representations_configuration-properties.adoc[leveloffset=+1]
+include::_ugvro_simplified-representations_apache-isis-profile.adoc[leveloffset=+1]
+include::_ugvro_simplified-representations_domain-object.adoc[leveloffset=+1]
+include::_ugvro_simplified-representations_object-collection.adoc[leveloffset=+1]
+include::_ugvro_simplified-representations_action-invocation.adoc[leveloffset=+1]
+include::_ugvro_simplified-representations_other-representations.adoc[leveloffset=+1]
+include::_ugvro_simplified-representations_configuration-properties.adoc[leveloffset=+1]
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_action-invocation.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_action-invocation.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_action-invocation.adoc
new file mode 100644
index 0000000..d1ac550
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_action-invocation.adoc
@@ -0,0 +1,128 @@
+[[_ugvro_simplified-representations_action-invocation]]
+= Action Invocation
+: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/
+
+
+
+When an action is invoked, it can return a domain object, a list, a scalar, or return nothing.
+
+== Returning an Object
+
+If the action returned an object, then the domain object representation described
+xref:../ugvro/ugvro.adoc#__ugvro_simplified-representations_domain-object[above] is returned.
+
+For example, using the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp], accessing
+this resource:
+
+[source]
+----
+http://localhost:8080/restful/objects/TODO/45/actions/updateCost/invoke
+----
+
+with an `Accept` request header of:
+
+[source]
+----
+Accept: application/json;profile="urn:org.apache.isis/v1"
+----
+
+returns the following representation:
+
+[source]
+----
+
+{
+  "$$href" : "http://localhost:8080/restful/objects/TODO/45",
+  "$$instanceId" : "45",
+  "$$title" : "Buy bread due by 2015-12-04",
+  "description" : "Buy bread",
+  "category" : "Domestic",
+  "subcategory" : "Shopping",
+  "complete" : false,
+  ...
+  "similarTo" : [ ... ]
+  ...
+  "$$ro" : { ... }
+}
+----
+
+with a `Content-Type` of:
+
+[source]
+----
+Content-Type: application/json;profile="urn:org.apache.isis/v1";repr-type="object"
+----
+
+\... in other words no different to a representation obtained of the returned domain object directly.
+
+
+== Returning a List
+
+On the other hand if the action returned a list (a "standalone" collection, then an array representation is returned.
+This is very similar to that returned by a
+xref:../ugvro/ugvro.adoc#__ugvro_simplified-representations_object-collection[(parented) object collection], though with a
+slightly different `Content-Type` to distinguish.
+
+For example, using the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp], accessing
+this resource:
+
+[source]
+----
+http://localhost:8080/restful/services/ToDoItems/actions/notYetComplete/invoke
+----
+
+with an `Accept` request header of:
+
+[source]
+----
+Accept: application/json;profile="urn:org.apache.isis/v1"
+----
+
+returns the following representation:
+
+[source]
+----
+[ {
+  "$$href" : "http://localhost:8080/restful/objects/TODO/45",
+  "$$instanceId" : "45",
+  "$$title" : "Buy bread due by 2015-12-04",
+  "description" : "Buy bread",
+  "category" : "Domestic",
+  ...
+}, {
+  "$$href" : "http://localhost:8080/restful/objects/TODO/46",
+  "$$instanceId" : "46",
+  "$$title" : "Buy milk due by 2015-12-04",
+  "description" : "Buy milk",
+  "category" : "Domestic",
+  ...
+},
+...
+, {
+  "$$ro" : {
+    "links" : [ ... ]
+    "resulttype" : "list",
+    "result" : { ... }
+      "value" : [ ... ],
+      "links" : [ ... ],
+      "extensions" : { }
+    }
+  }
+} ]
+----
+
+with a `Content-Type` header:
+
+[source]
+----
+Content-Type: application/json;profile="urn:org.apache.isis/v1";repr-type="list"
+----
+
+== Returning Scalar/Nothing
+
+Note that actions returning scalar values or nothing (which includes `void` actions) are not supported; for these the
+regular RO spec representation will be returned.
+
+

[19/58] [abbrv] isis git commit: ISIS-1521: more reorganizing of images and also resources for dg.adoc

[da...@apache.org]

ISIS-1521: more reorganizing of images and also resources for dg.adoc


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/add8cef9
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/add8cef9
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/add8cef9

Branch: refs/heads/wip
Commit: add8cef9b2802d614724b8c379367664bbdf8fb6
Parents: 58298b2
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Fri Apr 14 12:30:37 2017 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Thu Apr 20 09:09:29 2017 +0100

----------------------------------------------------------------------
 .../asciidoc/guides/dg/_dg_ide_eclipse.adoc     |  22 +-
 .../asciidoc/guides/dg/_dg_ide_intellij.adoc    |  98 ++--
 .../eclipse/eclipse-010-windows-preferences.png | Bin 37417 -> 0 bytes
 .../eclipse/eclipse-025-project-properties.png  | Bin 76584 -> 0 bytes
 .../eclipse/eclipse-100-project-support.png     | Bin 54952 -> 0 bytes
 .../eclipse/eclipse-110-project-support.png     | Bin 53218 -> 0 bytes
 .../dev-env/eclipse/eclipse-120-console.png     | Bin 12887 -> 0 bytes
 .../eclipse-200-enhancer-fails-duplicates.png   | Bin 47581 -> 0 bytes
 .../eclipse-210-enhancer-fails-duplicates.png   | Bin 11776 -> 0 bytes
 .../eclipse-220-enhancer-fails-duplicates.png   | Bin 54752 -> 0 bytes
 .../010-installing/010-welcome-page.png         | Bin 29192 -> 0 bytes
 .../010-installing/020-choose-location.png      | Bin 24433 -> 0 bytes
 .../010-installing/030-installation-options.png | Bin 18300 -> 0 bytes
 .../010-installing/040-start-menu-folder.png    | Bin 26120 -> 0 bytes
 .../010-installing/050-completing.png           | Bin 26499 -> 0 bytes
 .../060-import-settings-or-not.png              | Bin 11691 -> 0 bytes
 .../010-installing/070-set-ui-theme.png         | Bin 87739 -> 0 bytes
 .../010-new-project-create.png                  | Bin 14048 -> 0 bytes
 .../020-java-project-setup-jdk.png              | Bin 29837 -> 0 bytes
 .../030-java-project-select-jdk.png             | Bin 16597 -> 0 bytes
 .../020-create-new-project/040-sdk-selected.png | Bin 24884 -> 0 bytes
 .../050-name-and-location.png                   | Bin 11407 -> 0 bytes
 .../020-create-new-project/060-create-dir.png   | Bin 8424 -> 0 bytes
 .../010-settings-import-jar.png                 | Bin 13712 -> 0 bytes
 .../030-import-settings/020-select-all.png      | Bin 8863 -> 0 bytes
 .../030-import-settings/030-restart.png         | Bin 8209 -> 0 bytes
 .../030-import-settings/040-file-templates.png  | Bin 39841 -> 0 bytes
 .../030-import-settings/050-live-templates.png  | Bin 38456 -> 0 bytes
 .../010-build-automatically.png                 | Bin 50767 -> 0 bytes
 .../020-annotation-processor.png                | Bin 67560 -> 0 bytes
 .../010-maven-installation.png                  | Bin 43353 -> 0 bytes
 .../020-maven-configuration.png                 | Bin 53554 -> 0 bytes
 .../044-other-settings-misc/010-auto-import.png | Bin 31963 -> 0 bytes
 .../050-some-plugins/010-some-plugins.png       | Bin 45812 -> 0 bytes
 .../020-some-plugins-confirmation.png           | Bin 35687 -> 0 bytes
 .../maven-helper/010-dependency-tab.png         | Bin 64588 -> 0 bytes
 .../maven-helper/020-dependency-as-tree.png     | Bin 44040 -> 0 bytes
 .../maven-helper/030-maven-run-goal.png         | Bin 91806 -> 0 bytes
 .../maven-helper/040-maven-quick-run.png        | Bin 83850 -> 0 bytes
 .../010-duplicate-classes.png                   | Bin 115681 -> 0 bytes
 .../070-advanced/002-compiler-exclude.png       | Bin 31775 -> 0 bytes
 .../070-advanced/004-gradle-output.png          | Bin 23091 -> 0 bytes
 .../070-advanced/005-gradle-output.png          | Bin 30890 -> 0 bytes
 .../070-advanced/006-livereload-js.png          | Bin 80581 -> 0 bytes
 ...10-dcevm-list-of-found-jdk-installations.png | Bin 44267 -> 0 bytes
 .../070-advanced/020-dcevm-once-installed.png   | Bin 44435 -> 0 bytes
 .../030-dcevm-intellij-project-structure.png    | Bin 62740 -> 0 bytes
 .../040-dcevm-run-configuration.png             | Bin 47864 -> 0 bytes
 .../010-maven-modules-view.png                  | Bin 103134 -> 0 bytes
 .../020-adding-another-module.png               | Bin 23846 -> 0 bytes
 .../030-other-module-added.png                  | Bin 111516 -> 0 bytes
 .../040-ignoring-modules.png                    | Bin 120475 -> 0 bytes
 .../050-ignoring-modules-2.png                  | Bin 17050 -> 0 bytes
 .../060-ignored-modules.png                     | Bin 92428 -> 0 bytes
 .../010-run-configuration.png                   | Bin 34826 -> 0 bytes
 .../020-datanucleus-enhancer-goal.png           | Bin 8491 -> 0 bytes
 .../030-running-unit-tests.png                  | Bin 29351 -> 0 bytes
 ...040-running-unit-tests-run-configuration.png | Bin 37582 -> 0 bytes
 ...ning-integration-tests-run-configuration.png | Bin 40655 -> 0 bytes
 .../010-file-project-structure.png              | Bin 19261 -> 0 bytes
 .../200-project-sdk/020-select-jdk.png          | Bin 43375 -> 0 bytes
 .../030-select-jdk-directory.png                | Bin 20740 -> 0 bytes
 .../200-project-sdk/040-set-project-level.png   | Bin 40868 -> 0 bytes
 .../050-isis-language-level-7.png               | Bin 53883 -> 0 bytes
 .../060-app-language-level-8.png                | Bin 58257 -> 0 bytes
 .../250-new-project/010-new-project.png         | Bin 20564 -> 0 bytes
 .../250-new-project/020-new-project-name.png    | Bin 11273 -> 0 bytes
 .../030-new-project-new-window.png              | Bin 9785 -> 0 bytes
 .../040-new-module-from-existing-sources.png    | Bin 27953 -> 0 bytes
 .../050-specify-source-folder.png               | Bin 23884 -> 0 bytes
 .../250-new-project/060-import-using-maven.png  | Bin 11739 -> 0 bytes
 .../070-import-module-settings.png              | Bin 36175 -> 0 bytes
 .../250-new-project/080-maven-profiles.png      | Bin 9922 -> 0 bytes
 .../250-new-project/090-maven-coordinates.png   | Bin 13546 -> 0 bytes
 .../100-annotation-processing.png               | Bin 54602 -> 0 bytes
 .../250-new-project/110-parameter8.png          | Bin 41948 -> 0 bytes
 .../120-clean-generate-sources.png              | Bin 5988 -> 0 bytes
 .../010-configuring-the-compiler.png            | Bin 40826 -> 0 bytes
 .../run-debug-configuration-single-module.png   | Bin 44274 -> 0 bytes
 .../eclipse/eclipse-010-windows-preferences.png | Bin 0 -> 37417 bytes
 .../eclipse/eclipse-025-project-properties.png  | Bin 0 -> 76584 bytes
 .../eclipse/eclipse-100-project-support.png     | Bin 0 -> 54952 bytes
 .../eclipse/eclipse-110-project-support.png     | Bin 0 -> 53218 bytes
 .../dg/images/eclipse/eclipse-120-console.png   | Bin 0 -> 12887 bytes
 .../eclipse-200-enhancer-fails-duplicates.png   | Bin 0 -> 47581 bytes
 .../eclipse-210-enhancer-fails-duplicates.png   | Bin 0 -> 11776 bytes
 .../eclipse-220-enhancer-fails-duplicates.png   | Bin 0 -> 54752 bytes
 .../010-installing/010-welcome-page.png         | Bin 0 -> 29192 bytes
 .../010-installing/020-choose-location.png      | Bin 0 -> 24433 bytes
 .../010-installing/030-installation-options.png | Bin 0 -> 18300 bytes
 .../010-installing/040-start-menu-folder.png    | Bin 0 -> 26120 bytes
 .../010-installing/050-completing.png           | Bin 0 -> 26499 bytes
 .../060-import-settings-or-not.png              | Bin 0 -> 11691 bytes
 .../010-installing/070-set-ui-theme.png         | Bin 0 -> 87739 bytes
 .../010-new-project-create.png                  | Bin 0 -> 14048 bytes
 .../020-java-project-setup-jdk.png              | Bin 0 -> 29837 bytes
 .../030-java-project-select-jdk.png             | Bin 0 -> 16597 bytes
 .../020-create-new-project/040-sdk-selected.png | Bin 0 -> 24884 bytes
 .../050-name-and-location.png                   | Bin 0 -> 11407 bytes
 .../020-create-new-project/060-create-dir.png   | Bin 0 -> 8424 bytes
 .../010-settings-import-jar.png                 | Bin 0 -> 13712 bytes
 .../030-import-settings/020-select-all.png      | Bin 0 -> 8863 bytes
 .../030-import-settings/030-restart.png         | Bin 0 -> 8209 bytes
 .../030-import-settings/040-file-templates.png  | Bin 0 -> 39841 bytes
 .../030-import-settings/050-live-templates.png  | Bin 0 -> 38456 bytes
 .../010-build-automatically.png                 | Bin 0 -> 50767 bytes
 .../020-annotation-processor.png                | Bin 0 -> 67560 bytes
 .../010-maven-installation.png                  | Bin 0 -> 43353 bytes
 .../020-maven-configuration.png                 | Bin 0 -> 53554 bytes
 .../044-other-settings-misc/010-auto-import.png | Bin 0 -> 31963 bytes
 .../050-some-plugins/010-some-plugins.png       | Bin 0 -> 45812 bytes
 .../020-some-plugins-confirmation.png           | Bin 0 -> 35687 bytes
 .../maven-helper/010-dependency-tab.png         | Bin 0 -> 64588 bytes
 .../maven-helper/020-dependency-as-tree.png     | Bin 0 -> 44040 bytes
 .../maven-helper/030-maven-run-goal.png         | Bin 0 -> 91806 bytes
 .../maven-helper/040-maven-quick-run.png        | Bin 0 -> 83850 bytes
 .../010-duplicate-classes.png                   | Bin 0 -> 115681 bytes
 .../070-advanced/002-compiler-exclude.png       | Bin 0 -> 31775 bytes
 .../070-advanced/004-gradle-output.png          | Bin 0 -> 23091 bytes
 .../070-advanced/005-gradle-output.png          | Bin 0 -> 30890 bytes
 .../070-advanced/006-livereload-js.png          | Bin 0 -> 80581 bytes
 ...10-dcevm-list-of-found-jdk-installations.png | Bin 0 -> 44267 bytes
 .../070-advanced/020-dcevm-once-installed.png   | Bin 0 -> 44435 bytes
 .../030-dcevm-intellij-project-structure.png    | Bin 0 -> 62740 bytes
 .../040-dcevm-run-configuration.png             | Bin 0 -> 47864 bytes
 .../010-maven-modules-view.png                  | Bin 0 -> 103134 bytes
 .../020-adding-another-module.png               | Bin 0 -> 23846 bytes
 .../030-other-module-added.png                  | Bin 0 -> 111516 bytes
 .../040-ignoring-modules.png                    | Bin 0 -> 120475 bytes
 .../050-ignoring-modules-2.png                  | Bin 0 -> 17050 bytes
 .../060-ignored-modules.png                     | Bin 0 -> 92428 bytes
 .../010-run-configuration.png                   | Bin 0 -> 34826 bytes
 .../020-datanucleus-enhancer-goal.png           | Bin 0 -> 8491 bytes
 .../030-running-unit-tests.png                  | Bin 0 -> 29351 bytes
 ...040-running-unit-tests-run-configuration.png | Bin 0 -> 37582 bytes
 ...ning-integration-tests-run-configuration.png | Bin 0 -> 40655 bytes
 .../010-file-project-structure.png              | Bin 0 -> 19261 bytes
 .../200-project-sdk/020-select-jdk.png          | Bin 0 -> 43375 bytes
 .../030-select-jdk-directory.png                | Bin 0 -> 20740 bytes
 .../200-project-sdk/040-set-project-level.png   | Bin 0 -> 40868 bytes
 .../050-isis-language-level-7.png               | Bin 0 -> 53883 bytes
 .../060-app-language-level-8.png                | Bin 0 -> 58257 bytes
 .../250-new-project/010-new-project.png         | Bin 0 -> 20564 bytes
 .../250-new-project/020-new-project-name.png    | Bin 0 -> 11273 bytes
 .../030-new-project-new-window.png              | Bin 0 -> 9785 bytes
 .../040-new-module-from-existing-sources.png    | Bin 0 -> 27953 bytes
 .../050-specify-source-folder.png               | Bin 0 -> 23884 bytes
 .../250-new-project/060-import-using-maven.png  | Bin 0 -> 11739 bytes
 .../070-import-module-settings.png              | Bin 0 -> 36175 bytes
 .../250-new-project/080-maven-profiles.png      | Bin 0 -> 9922 bytes
 .../250-new-project/090-maven-coordinates.png   | Bin 0 -> 13546 bytes
 .../100-annotation-processing.png               | Bin 0 -> 54602 bytes
 .../250-new-project/110-parameter8.png          | Bin 0 -> 41948 bytes
 .../120-clean-generate-sources.png              | Bin 0 -> 5988 bytes
 .../010-configuring-the-compiler.png            | Bin 0 -> 40826 bytes
 .../run-debug-configuration-single-module.png   | Bin 0 -> 44274 bytes
 .../dev-env/eclipse/isis-templates.xml          | 465 -------------------
 .../dev-env/eclipse/jmock2-templates.xml        |   9 -
 .../dev-env/eclipse/junit4-templates.xml        |  13 -
 .../appendices/dev-env/intellij/.gitignore      |   1 -
 .../intellij/isis-settings-code-style.jar       | Bin 3512 -> 0 bytes
 .../intellij/isis-settings-file-templates.jar   | Bin 10702 -> 0 bytes
 .../intellij/isis-settings-live-templates.jar   | Bin 7492 -> 0 bytes
 .../dev-env/intellij/other/.gitignore           |   1 -
 .../intellij/other/dan-settings-keymaps.jar     | Bin 2200 -> 0 bytes
 .../intellij/other/dan-settings-uisettings.jar  | Bin 861 -> 0 bytes
 .../dg/resources/eclipse/isis-templates.xml     | 465 +++++++++++++++++++
 .../dg/resources/eclipse/jmock2-templates.xml   |   9 +
 .../dg/resources/eclipse/junit4-templates.xml   |  13 +
 .../guides/dg/resources/intellij/.gitignore     |   1 +
 .../intellij/isis-settings-code-style.jar       | Bin 0 -> 3512 bytes
 .../intellij/isis-settings-file-templates.jar   | Bin 0 -> 10702 bytes
 .../intellij/isis-settings-live-templates.jar   | Bin 0 -> 7492 bytes
 .../dg/resources/intellij/other/.gitignore      |   1 +
 .../intellij/other/dan-settings-keymaps.jar     | Bin 0 -> 2200 bytes
 .../intellij/other/dan-settings-uisettings.jar  | Bin 0 -> 861 bytes
 176 files changed, 549 insertions(+), 549 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_eclipse.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_eclipse.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_eclipse.adoc
index f2a3e5b..2d310e7 100644
--- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_eclipse.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_eclipse.adoc
@@ -37,9 +37,9 @@ application into Eclipse and configure to use with the JDO Objectstore.
 
 We provide a set of editor templates.  These are used to add new methods to existing classes.  (These are equivalent to the xref:dg.adoc#__dg_ide_intellij_live-templates[IntelliJ live templates]):
 
-* `is` (Apache Isis domain objects).  link:./resources/appendices/dev-env/eclipse/isis-templates.xml[Download]
-* `ju` (for JUnit tests) link:./resources/appendices/dev-env/eclipse/junit4-templates.xml[Download]
-* `jm` (for JMock mocks or libraries) link:./resources/appendices/dev-env/eclipse/jmock2-templates.xml[Download]
+* `is` (Apache Isis domain objects).  link:./resources/eclipse/isis-templates.xml[Download]
+* `ju` (for JUnit tests) link:./resources/eclipse/junit4-templates.xml[Download]
+* `jm` (for JMock mocks or libraries) link:./resources/eclipse/jmock2-templates.xml[Download]
 
 
 To install, download each XML file, then go to `Windows > Preferences > Java > Editor > Templates` and choose `Import`.
@@ -65,12 +65,12 @@ Make sure you are in the 'Java' Perspective, not the 'Java EE' Perspective.
 
 In Eclipse, for the _domain object model_ project, first add DataNucleus support:
 
-image::{_imagesdir}appendices/dev-env/eclipse/eclipse-100-project-support.png[width="600px",link="{_imagesdir}appendices/dev-env/eclipse/eclipse-100-project-support.png"]
+image::{_imagesdir}eclipse/eclipse-100-project-support.png[width="600px",link="{_imagesdir}eclipse/eclipse-100-project-support.png"]
 
 
 Then turn on Auto-Enhancement:
 
-image::{_imagesdir}appendices/dev-env/eclipse/eclipse-110-project-support.png[width="600px",link="{_imagesdir}appendices/dev-env/eclipse/eclipse-110-project-support.png"]
+image::{_imagesdir}eclipse/eclipse-110-project-support.png[width="600px",link="{_imagesdir}eclipse/eclipse-110-project-support.png"]
 
 
 === Update the classpath
@@ -83,11 +83,11 @@ See the earlier section on xref:ugfun.adoc#_ugfun_getting-started_datanucleus-en
 Then, tell DataNucleus to use the project classpath:
 
 
-image::{_imagesdir}/appendices/dev-env/eclipse/eclipse-010-windows-preferences.png[width="750px",link="{_imagesdir}/appendices/dev-env/eclipse/eclipse-010-windows-preferences.png"]
+image::{_imagesdir}eclipse/eclipse-010-windows-preferences.png[width="750px",link="{_imagesdir}/appendices/dev-env/eclipse/eclipse-010-windows-preferences.png"]
 
 When the enhancer runs, it will print out to the console:
 
-image::{_imagesdir}/appendices/dev-env/eclipse/eclipse-120-console.png[width="500px",link="{_imagesdir}/appendices/dev-env/eclipse/eclipse-120-console.png"]
+image::{_imagesdir}eclipse/eclipse-120-console.png[width="500px",link="{_imagesdir}/appendices/dev-env/eclipse/eclipse-120-console.png"]
 
 
 
@@ -99,7 +99,7 @@ To fix this, we configure the enhancer to read from the `persistence.xml` file.
 
 As a prerequisite, first make sure that your domain object model has a `persistence.xml` file.  Then specify the `persistence-unit` in the project properties:
 
-image::{_imagesdir}/appendices/dev-env/eclipse/eclipse-025-project-properties.png[width="750px",link="{_imagesdir}/appendices/dev-env/eclipse/eclipse-025-project-properties.png"]
+image::{_imagesdir}eclipse/eclipse-025-project-properties.png[width="750px",link="{_imagesdir}/appendices/dev-env/eclipse/eclipse-025-project-properties.png"]
 
 
 === Workaround: If the enhancer fails
@@ -107,20 +107,20 @@ image::{_imagesdir}/appendices/dev-env/eclipse/eclipse-025-project-properties.pn
 On occasion it appears that Eclipse can attempt to run two instances of the DataNucleus enhancer. This is probably due to multiple Eclipse builders being defined; we've noticed multiple entries in the Eclipse's `Debug` view:
 
 
-image::{_imagesdir}/appendices/dev-env/eclipse/eclipse-210-enhancer-fails-duplicates.png[width="600px",link="{_imagesdir}/appendices/dev-env/eclipse/eclipse-210-enhancer-fails-duplicates.png"]
+image::{_imagesdir}eclipse/eclipse-210-enhancer-fails-duplicates.png[width="600px",link="{_imagesdir}/appendices/dev-env/eclipse/eclipse-210-enhancer-fails-duplicates.png"]
 
 
 At any rate, you'll know you've encountered this error if you see the following in the console:
 
 
-image::{_imagesdir}/appendices/dev-env/eclipse/eclipse-200-enhancer-fails-duplicates.png[width="600px",link="{_imagesdir}/appendices/dev-env/eclipse/eclipse-200-enhancer-fails-duplicates.png"]
+image::{_imagesdir}eclipse/eclipse-200-enhancer-fails-duplicates.png[width="600px",link="{_imagesdir}/appendices/dev-env/eclipse/eclipse-200-enhancer-fails-duplicates.png"]
 
 
 
 The best solution is to remove DataNucleus support and then to re-add it:
 
 
-image::{_imagesdir}/appendices/dev-env/eclipse/eclipse-220-enhancer-fails-duplicates.png[width="600px",link="{_imagesdir}/appendices/dev-env/eclipse/eclipse-220-enhancer-fails-duplicates.png"]
+image::{_imagesdir}eclipse/eclipse-220-enhancer-fails-duplicates.png[width="600px",link="{_imagesdir}/appendices/dev-env/eclipse/eclipse-220-enhancer-fails-duplicates.png"]
 
 
 If you consistently hit problems, then the final recourse is to disable the automatic enhancement and to remember to manually enhance your domain object model before each run.

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_intellij.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_intellij.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_intellij.adoc
index 152ddbb..46a6677 100644
--- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_intellij.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_intellij.adoc
@@ -29,37 +29,37 @@ https://www.jetbrains.com/idea/download/[Download] latest version of IntelliJ Co
 Start the wizard, click through the welcome page:
 
 .IntelliJ Installation Wizard - Welcome page
-image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/010-welcome-page.png[width="400px"]
+image::{_imagesdir}intellij-idea/010-installing/010-welcome-page.png[width="400px"]
 
 Choose the location to install the IDE:
 
 .IntelliJ Installation Wizard - Choose Location
-image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/020-choose-location.png[width="400px"]
+image::{_imagesdir}intellij-idea/010-installing/020-choose-location.png[width="400px"]
 
 Adjust any installation options as you prefer:
 
 .IntelliJ Installation Wizard - Installation Options
-image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/030-installation-options.png[width="400px"]
+image::{_imagesdir}intellij-idea/010-installing/030-installation-options.png[width="400px"]
 
 and the start menu:
 
 .IntelliJ Installation Wizard - Start Menu Folder
-image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/040-start-menu-folder.png[width="400px"]
+image::{_imagesdir}intellij-idea/010-installing/040-start-menu-folder.png[width="400px"]
 
 and finish up the wizard:
 
 .IntelliJ Installation Wizard - Completing the Wizard
-image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/050-completing.png[width="400px"]
+image::{_imagesdir}intellij-idea/010-installing/050-completing.png[width="400px"]
 
 Later on we'll specify the Apache Isis/ASF code style settings, so for now select `I do not want to import settings`:
 
 .IntelliJ Installation Wizard - Import Settings
-image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/060-import-settings-or-not.png[width="400px"]
+image::{_imagesdir}intellij-idea/010-installing/060-import-settings-or-not.png[width="400px"]
 
 Finally, if you are a trendy hipster, set the UI theme to Darcula:
 
 .IntelliJ Installation Wizard Set UI Theme
-image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/070-set-ui-theme.png[width="600px"]
+image::{_imagesdir}intellij-idea/010-installing/070-set-ui-theme.png[width="600px"]
 
 
 
@@ -72,31 +72,31 @@ In IntelliJ a project can contain multiple modules; these need not be physically
 Start off by creating a new project:
 
 .IntelliJ Create New Project
-image::{_imagesdir}appendices/dev-env/intellij-idea/020-create-new-project/010-new-project-create.png[width="400px"]
+image::{_imagesdir}intellij-idea/020-create-new-project/010-new-project-create.png[width="400px"]
 
 
 We want to create a new *Java* project:
 
 .IntelliJ Create New Project - Create a Java project
-image::{_imagesdir}appendices/dev-env/intellij-idea/020-create-new-project/020-java-project-setup-jdk.png[width="500px"]
+image::{_imagesdir}intellij-idea/020-create-new-project/020-java-project-setup-jdk.png[width="500px"]
 
 We therefore need to specify the JDK.  Apache Isis supports both Java 7 and Java 8.
 
 
 .IntelliJ Create New Java Project - Select the JDK
-image::{_imagesdir}appendices/dev-env/intellij-idea/020-create-new-project/030-java-project-select-jdk.png[width="250px"]
+image::{_imagesdir}intellij-idea/020-create-new-project/030-java-project-select-jdk.png[width="250px"]
 
 
 Specify the directory containing the JDK:
 
 .IntelliJ Create New Project - Select the JDK location
-image::{_imagesdir}appendices/dev-env/intellij-idea/020-create-new-project/050-name-and-location.png[width="400px"]
+image::{_imagesdir}intellij-idea/020-create-new-project/050-name-and-location.png[width="400px"]
 
 
 Finally allow IntelliJ to create the directory for the new project:
 
 .IntelliJ Create New Project
-image::{_imagesdir}appendices/dev-env/intellij-idea/020-create-new-project/060-create-dir.png[width="250px"]
+image::{_imagesdir}intellij-idea/020-create-new-project/060-create-dir.png[width="250px"]
 
 
 
@@ -107,14 +107,14 @@ image::{_imagesdir}appendices/dev-env/intellij-idea/020-create-new-project/060-c
 Next we recommend you import a set of standard file templates.  These are used to create new classes or supporting files:
 
 .File templates
-image::{_imagesdir}appendices/dev-env/intellij-idea/030-import-settings/040-file-templates.png[width="400px"]
+image::{_imagesdir}intellij-idea/030-import-settings/040-file-templates.png[width="400px"]
 
-The file templates are provided as a settings JAR file, namely *link:resources/appendices/dev-env/intellij/isis-settings-file-templates.jar[isis-settings-file-templates.jar]*.  Download this file.
+The file templates are provided as a settings JAR file, namely *link:resources/intellij/isis-settings-file-templates.jar[isis-settings-file-templates.jar]*.  Download this file.
 
 Next, import using `File > Import Settings`, specifying the directory that you have downloaded the file to:
 
 .IntelliJ Import Settings - Specify JAR file
-image::{_imagesdir}appendices/dev-env/intellij-idea/030-import-settings/010-settings-import-jar.png[width="400px"]
+image::{_imagesdir}intellij-idea/030-import-settings/010-settings-import-jar.png[width="400px"]
 
 Select all the categories (there should just be one), and hit OK.  then hit restart.
 
@@ -141,7 +141,7 @@ in your home directory:
 We also recommend you import a set  of live templates.  These are used to add new methods to existing classes:
 
 .Live templates
-image::{_imagesdir}appendices/dev-env/intellij-idea/030-import-settings/050-live-templates.png[width="600px"]
+image::{_imagesdir}intellij-idea/030-import-settings/050-live-templates.png[width="600px"]
 
 The live templates have a prefix of prefixed either:
 
@@ -150,7 +150,7 @@ The live templates have a prefix of prefixed either:
 * `jm` : for JMock mocks or libraries
 * `ad` : for Asciidoc documentation; a full list can be found in the xref:dg.adoc#_dg_asciidoc-templates[appendix].
 
-The live templates are also provided as a settings JAR file, namely *link:resources/appendices/dev-env/intellij/isis-settings-live-templates.jar[isis-settings-live-templates.jar]*.
+The live templates are also provided as a settings JAR file, namely *link:resources/intellij/isis-settings-live-templates.jar[isis-settings-live-templates.jar]*.
 Download and import (as for the previous settings JAR files).
 
 
@@ -160,7 +160,7 @@ Download and import (as for the previous settings JAR files).
 === Coding Standards
 
 Next, we suggest you recommend you import settings for standard ASF/Apache Isis coding conventions.  This file is also
-provided as a settings file, namely *link:resources/appendices/dev-env/intellij/isis-settings-code-style.jar[isis-settings-code-style.jar]*.  Download and import (as for the above settings JAR files).
+provided as a settings file, namely *link:resources/intellij/isis-settings-code-style.jar[isis-settings-code-style.jar]*.  Download and import (as for the above settings JAR files).
 
 
 
@@ -172,13 +172,13 @@ There are also some other settings that influence the compiler.  We highly recom
 On the *Compiler* Settings page, ensure that `build automatically` is enabled (and optionally `compile independent modules in parallel`):
 
 .IntelliJ Compiler Settings
-image::{_imagesdir}appendices/dev-env/intellij-idea/040-other-settings-compiler/010-build-automatically.png[width="700px"]
+image::{_imagesdir}intellij-idea/040-other-settings-compiler/010-build-automatically.png[width="700px"]
 
 
 On the *Annotation Processors* page, enable and adjust for the 'default' setting:
 
 .IntelliJ Annotation Processor Settings
-image::{_imagesdir}appendices/dev-env/intellij-idea/040-other-settings-compiler/020-annotation-processor.png[width="700px"]
+image::{_imagesdir}intellij-idea/040-other-settings-compiler/020-annotation-processor.png[width="700px"]
 
 This setting enables the generation of the `Q*` classes for DataNucleus type-safe queries, as well as being required
 for frameworks such as xref:_cg_ide_project-lombok[Project Lombok].
@@ -200,12 +200,12 @@ There are also some other settings for Maven that we recommend you adjust (thoug
 First, specify an up-to-date Maven installation, using `File > Settings` (or `IntelliJ > Preferences` if on MacOS):
 
 .IntelliJ Maven Settings - Installation
-image::{_imagesdir}appendices/dev-env/intellij-idea/042-other-settings-maven/010-maven-installation.png[width="700px"]
+image::{_imagesdir}intellij-idea/042-other-settings-maven/010-maven-installation.png[width="700px"]
 
 Still on the Maven settings page, configure as follows:
 
 .IntelliJ Maven Settings - Configuration
-image::{_imagesdir}appendices/dev-env/intellij-idea/042-other-settings-maven/020-maven-configuration.png[width="700px"]
+image::{_imagesdir}intellij-idea/042-other-settings-maven/020-maven-configuration.png[width="700px"]
 
 
 === Other Settings (Misc)
@@ -215,7 +215,7 @@ These settings are optional but also recommended.
 On the *auto import* page, check the `optimize imports on the fly` and `add unambiguous imports on the fly`
 
 .IntelliJ Maven Settings - Auto Import
-image::{_imagesdir}appendices/dev-env/intellij-idea/044-other-settings-misc/010-auto-import.png[width="700px"]
+image::{_imagesdir}intellij-idea/044-other-settings-misc/010-auto-import.png[width="700px"]
 
 
 
@@ -228,18 +228,18 @@ Let's load in some actual code!  We do this by importing the Maven modules.
 First up, open up the Maven tool window (`View > Tool Windows > Maven Projects`).  You can then use the 'plus' button to add Maven modules.  In the screenshot you can see we've loaded in Apache Isis core; the modules are listed in the _Maven Projects_ window and corresponding (IntelliJ) modules are shown in the _Projects_ window:
 
 .IntelliJ Maven Module Management - Importing Maven modules
-image::{_imagesdir}appendices/dev-env/intellij-idea/100-maven-module-mgmt/010-maven-modules-view.png[width="730px"]
+image::{_imagesdir}intellij-idea/100-maven-module-mgmt/010-maven-modules-view.png[width="730px"]
 
 We can then import another module (from some other directory).  For example, here we are importing the Isis Addons' todoapp example:
 
 
 .IntelliJ Maven Module Management - Importing another Module
-image::{_imagesdir}appendices/dev-env/intellij-idea/100-maven-module-mgmt/020-adding-another-module.png[width="400px"]
+image::{_imagesdir}intellij-idea/100-maven-module-mgmt/020-adding-another-module.png[width="400px"]
 
 You should then see the new Maven module loaded in the _Projects_ window and also the _Maven Projects_ window:
 
 .IntelliJ Maven Module Management -
-image::{_imagesdir}appendices/dev-env/intellij-idea/100-maven-module-mgmt/030-other-module-added.png[width="730px"]
+image::{_imagesdir}intellij-idea/100-maven-module-mgmt/030-other-module-added.png[width="730px"]
 
 If any dependencies are already loaded in the project, then IntelliJ will automatically update the CLASSPATH to resolve to locally held modules (rather from `.m2/repository` folder).  So, for example (assuming that the `<version>` is correct, of course), the Isis todoapp will have local dependencies on the Apache Isis core.
 
@@ -248,17 +248,17 @@ You can press F4 (or use `File > Project Structure`) to see the resolved classpa
 If you want to focus on one set of code (eg the Isis todoapp but not Apache Isis core) then you _could_ remove the module; but better is to ignore those modules.  This will remove from the the _Projects_ window but keep them available in the _Maven Projects_ window for when you next want to work on them:
 
 .IntelliJ Maven Module Management - Ignoring Modules
-image::{_imagesdir}appendices/dev-env/intellij-idea/100-maven-module-mgmt/040-ignoring-modules.png[width="730px"]
+image::{_imagesdir}intellij-idea/100-maven-module-mgmt/040-ignoring-modules.png[width="730px"]
 
 Confirm that it's ok to ignore these modules:
 
 .IntelliJ Maven Module Management - Ignoring Modules (ctd)
-image::{_imagesdir}appendices/dev-env/intellij-idea/100-maven-module-mgmt/050-ignoring-modules-2.png[width="300px"]
+image::{_imagesdir}intellij-idea/100-maven-module-mgmt/050-ignoring-modules-2.png[width="300px"]
 
 All being well you should see that the _Projects_ window now only contains the code you are working on.  Its classpath dependencies will be adjusted (eg to resolve to Apache Isis core from `.m2/repository`):
 
 .IntelliJ Maven Module Management - Updated Projects Window
-image::{_imagesdir}appendices/dev-env/intellij-idea/100-maven-module-mgmt/060-ignored-modules.png[width="730px"]
+image::{_imagesdir}intellij-idea/100-maven-module-mgmt/060-ignored-modules.png[width="730px"]
 
 
 
@@ -275,7 +275,7 @@ Once you've imported your Isis application, we should run it.  We do this by cre
 Set up the details as follows:
 
 .IntelliJ Running the App - Run Configuration
-image::{_imagesdir}appendices/dev-env/intellij-idea/110-running-the-app/010-run-configuration.png[width="600px"]
+image::{_imagesdir}intellij-idea/110-running-the-app/010-run-configuration.png[width="600px"]
 
 We specify the `Main class` to be `org.apache.isis.WebServer`; this is a wrapper around Jetty.  It's possible to pass program arguments to this (eg to automatically install fixtures), but for now leave this blank.
 
@@ -284,7 +284,7 @@ Also note that `Use classpath of module` is the webapp module for your app, and
 Next, and most importantly, configure the DataNucleus enhancer to run for your `dom` goal.  This can be done by defining a Maven goal to run before the app:
 
 .IntelliJ Running the App - Datanucleus Enhancer Goal
-image::{_imagesdir}appendices/dev-env/intellij-idea/110-running-the-app/020-datanucleus-enhancer-goal.png[width="400px"]
+image::{_imagesdir}intellij-idea/110-running-the-app/020-datanucleus-enhancer-goal.png[width="400px"]
 
 The `-o` flag in the goal means run off-line; this will run faster.
 
@@ -299,12 +299,12 @@ You should now be able to run the app using `Run > Run Configuration`.  The same
 The easiest way to run the unit tests is just to right click on the `dom` module in the _Project Window_, and choose run unit tests.  Hopefully your tests will pass (!).
 
 .IntelliJ Running the App - Unit Tests Run Configuration
-image::{_imagesdir}appendices/dev-env/intellij-idea/110-running-the-app/030-running-unit-tests.png[width="600px"]
+image::{_imagesdir}intellij-idea/110-running-the-app/030-running-unit-tests.png[width="600px"]
 
 As a side-effect, this will create a run configuration, very similar to the one we manually created for the main app:
 
 .IntelliJ Running the App - Unit Tests Run Configuration
-image::{_imagesdir}appendices/dev-env/intellij-idea/110-running-the-app/040-running-unit-tests-run-configuration.png[width="600px"]
+image::{_imagesdir}intellij-idea/110-running-the-app/040-running-unit-tests-run-configuration.png[width="600px"]
 
 Thereafter, you should run units by selecting this configuration (if you use the right click approach you'll end up with lots of run configurations, all similar).
 
@@ -317,13 +317,13 @@ Integration tests can be run in the same way as unit tests, however the `dom` mo
 One approach is to initially run the tests use the right click on the `integtests` module; the tests will fail because the code won't have been enhanced, but we can then go and update the run configuration to run the datanucleus enhancer goal (same as when running the application):
 
 .IntelliJ Running the App - Integration Tests Run Configuration
-image::{_imagesdir}appendices/dev-env/intellij-idea/110-running-the-app/050-running-integration-tests-run-configuration.png[width="600px"]
+image::{_imagesdir}intellij-idea/110-running-the-app/050-running-integration-tests-run-configuration.png[width="600px"]
 
 
 
 Also make sure that the `search for tests` radio button is set to `In single module`:
 
-image::{_imagesdir}appendices/dev-env/intellij-idea/400-running-integtests/run-debug-configuration-single-module.png[width="600px",link="{_imagesdir}appendices/dev-env/intellij-idea/400-running-integtests/run-debug-configuration-single-module.png"]
+image::{_imagesdir}intellij-idea/400-running-integtests/run-debug-configuration-single-module.png[width="600px",link="{_imagesdir}intellij-idea/400-running-integtests/run-debug-configuration-single-module.png"]
 
 If this radio button is set to one of the other options then you may obtain class loading issues; these result from IntelliJ attempting to run unit tests of the `dom` project that depend on test classes in that module, but using the classpath of the `integtests` module whereby the `dom` test-classes (`test-jar` artifact) are not exposed on the Maven classpath.
 
@@ -438,7 +438,7 @@ Useful if you are doing any authoring of documents.
 Some others you might like to explore are:
 
 .IntelliJ Plugins
-image::{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/020-some-plugins-confirmation.png[width="600px"]
+image::{_imagesdir}intellij-idea/050-some-plugins/020-some-plugins-confirmation.png[width="600px"]
 
 
 [[__dg_ide_intellij_hints-and-tips_plugins_maven-helper-plugin]]
@@ -448,19 +448,19 @@ This plugin provides a couple of great features.  One is better visualization of
 
 If you open a `pom.xml` file, you'll see an additional "Dependencies" tab:
 
-image::{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/010-dependency-tab.png[width="600px",link="{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/010-dependency-tab.png"]
+image::{_imagesdir}intellij-idea/050-some-plugins/maven-helper/010-dependency-tab.png[width="600px",link="{_imagesdir}intellij-idea/050-some-plugins/maven-helper/010-dependency-tab.png"]
 
 Clicking on this gives a graphical tree representation of the dependencies, similar to that obtained by `mvn dependency:tree`, but filterable.
 
-image::{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/020-dependency-as-tree.png[width="600px",link="{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/020-dependency-as-tree.png"]
+image::{_imagesdir}intellij-idea/050-some-plugins/maven-helper/020-dependency-as-tree.png[width="600px",link="{_imagesdir}intellij-idea/050-some-plugins/maven-helper/020-dependency-as-tree.png"]
 
 The plugin also provides the ability to easily run a Maven goal on a project:
 
-image::{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/030-maven-run-goal.png[width="600px",link="{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/030-maven-run-goal.png"]
+image::{_imagesdir}intellij-idea/050-some-plugins/maven-helper/030-maven-run-goal.png[width="600px",link="{_imagesdir}intellij-idea/050-some-plugins/maven-helper/030-maven-run-goal.png"]
 
 This menu can also be bound to a keystroke so that it is available as a pop-up:
 
-image::{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/040-maven-quick-run.png[width="600px",link="{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/040-maven-quick-run.png"]
+image::{_imagesdir}intellij-idea/050-some-plugins/maven-helper/040-maven-quick-run.png[width="600px",link="{_imagesdir}intellij-idea/050-some-plugins/maven-helper/040-maven-quick-run.png"]
 
 
 [[__dg_ide_intellij_troubleshooting]]
@@ -481,7 +481,7 @@ One thing worth knowing; IntelliJ actively scans the filesystem all the time.  I
 
 If you hit an error of "duplicate classes":
 
-image::{_imagesdir}appendices/dev-env/intellij-idea/060-troubleshooting/010-duplicate-classes.png[width="600px",link="{_imagesdir}appendices/dev-env/intellij-idea/060-troubleshooting/010-duplicate-classes.png"]
+image::{_imagesdir}intellij-idea/060-troubleshooting/010-duplicate-classes.png[width="600px",link="{_imagesdir}intellij-idea/060-troubleshooting/010-duplicate-classes.png"]
 
 then make sure you have correctly configured the xref:_cg_ide_intellij_other-settings-compiler[annotation processor]
 settings.  Pay attention in particular to the "Production sources directory" and "Test sources directory", that these
@@ -544,7 +544,7 @@ To use, you must disable the IntelliJ's automatic building of the 'dom' project.
 `File > Settings > Build, Execution, Deployment > Compiler > Excludes`, and then exclude the `.../dom/src/main/java`
 directory:
 
-image::{_imagesdir}appendices/dev-env/intellij-idea/070-advanced/002-compiler-exclude.png[width="800px",link="{_imagesdir}appendices/dev-env/intellij-idea/070-advanced/002-compiler-exclude.png"]
+image::{_imagesdir}intellij-idea/070-advanced/002-compiler-exclude.png[width="800px",link="{_imagesdir}intellij-idea/070-advanced/002-compiler-exclude.png"]
 
 
 The script can be run in the background using:
@@ -556,7 +556,7 @@ gradle -t --offline &
 
 from the command line (in the `dom` module).
 
-image::{_imagesdir}appendices/dev-env/intellij-idea/070-advanced/004-gradle-output.png[width="600px",link="{_imagesdir}appendices/dev-env/intellij-idea/070-advanced/004-gradle-output.png"]
+image::{_imagesdir}intellij-idea/070-advanced/004-gradle-output.png[width="600px",link="{_imagesdir}intellij-idea/070-advanced/004-gradle-output.png"]
 
 
 
@@ -627,7 +627,7 @@ gradle -t --offline -b liveReload.gradle &
 from the command line (in the `dom` module):
 
 
-image::{_imagesdir}appendices/dev-env/intellij-idea/070-advanced/005-gradle-output.png[width="600px",link="{_imagesdir}appendices/dev-env/intellij-idea/070-advanced/005-gradle-output.png"]
+image::{_imagesdir}intellij-idea/070-advanced/005-gradle-output.png[width="600px",link="{_imagesdir}intellij-idea/070-advanced/005-gradle-output.png"]
 
 
 Live reload also requires that the `isis.viewer.wicket.liveReloadUrl` configuration property is set appropriately:
@@ -641,7 +641,7 @@ isis.viewer.wicket.liveReloadUrl=http://localhost:35729/livereload.js?snipver=1
 You can confirm the script is loaded correctly using the web browser's development tools, eg:
 
 
-image::{_imagesdir}appendices/dev-env/intellij-idea/070-advanced/006-livereload-js.png[width="800px",link="{_imagesdir}appendices/dev-env/intellij-idea/070-advanced/006-livereload-js.png"]
+image::{_imagesdir}intellij-idea/070-advanced/006-livereload-js.png[width="800px",link="{_imagesdir}intellij-idea/070-advanced/006-livereload-js.png"]
 
 
 
@@ -676,21 +676,21 @@ on Windows, that means running as `Administrator`.
 
 After a few seconds this will display a dialog listing all installations of JDK that have been found:
 
-image::{_imagesdir}appendices/dev-env/intellij-idea/070-advanced/010-dcevm-list-of-found-jdk-installations.png[width="600px",link="{_imagesdir}appendices/dev-env/intellij-idea/070-advanced/010-dcevm-list-of-found-jdk-installations.png"]
+image::{_imagesdir}intellij-idea/070-advanced/010-dcevm-list-of-found-jdk-installations.png[width="600px",link="{_imagesdir}intellij-idea/070-advanced/010-dcevm-list-of-found-jdk-installations.png"]
 
 
 Select the corresponding installation, and select `Replace by DCEVM`.
 
-image::{_imagesdir}appendices/dev-env/intellij-idea/070-advanced/020-dcevm-once-installed.png[width="600px",link="{_imagesdir}appendices/dev-env/intellij-idea/070-advanced/020-dcevm-once-installed.png"]
+image::{_imagesdir}intellij-idea/070-advanced/020-dcevm-once-installed.png[width="600px",link="{_imagesdir}intellij-idea/070-advanced/020-dcevm-once-installed.png"]
 
 
 In IntelliJ, register the JDK in `File > Project Structure` dialog:
 
-image::{_imagesdir}appendices/dev-env/intellij-idea/070-advanced/030-dcevm-intellij-project-structure.png[width="600px",link="{_imagesdir}appendices/dev-env/intellij-idea/070-advanced/030-dcevm-intellij-project-structure.png"]
+image::{_imagesdir}intellij-idea/070-advanced/030-dcevm-intellij-project-structure.png[width="600px",link="{_imagesdir}intellij-idea/070-advanced/030-dcevm-intellij-project-structure.png"]
 
 Finally, in the run configuration, select the patched JDK:
 
-image::{_imagesdir}appendices/dev-env/intellij-idea/070-advanced/040-dcevm-run-configuration.png[width="600px",link="{_imagesdir}appendices/dev-env/intellij-idea/070-advanced/040-dcevm-run-configuration.png"]
+image::{_imagesdir}intellij-idea/070-advanced/040-dcevm-run-configuration.png[width="600px",link="{_imagesdir}intellij-idea/070-advanced/040-dcevm-run-configuration.png"]
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/eclipse/eclipse-010-windows-preferences.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/eclipse/eclipse-010-windows-preferences.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/eclipse/eclipse-010-windows-preferences.png
deleted file mode 100644
index 149a23b..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/eclipse/eclipse-010-windows-preferences.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/eclipse/eclipse-025-project-properties.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/eclipse/eclipse-025-project-properties.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/eclipse/eclipse-025-project-properties.png
deleted file mode 100644
index 120856c..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/eclipse/eclipse-025-project-properties.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/eclipse/eclipse-100-project-support.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/eclipse/eclipse-100-project-support.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/eclipse/eclipse-100-project-support.png
deleted file mode 100644
index 7068fb4..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/eclipse/eclipse-100-project-support.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/eclipse/eclipse-110-project-support.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/eclipse/eclipse-110-project-support.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/eclipse/eclipse-110-project-support.png
deleted file mode 100644
index 49d04a8..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/eclipse/eclipse-110-project-support.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/eclipse/eclipse-120-console.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/eclipse/eclipse-120-console.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/eclipse/eclipse-120-console.png
deleted file mode 100644
index 1e77587..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/eclipse/eclipse-120-console.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/eclipse/eclipse-200-enhancer-fails-duplicates.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/eclipse/eclipse-200-enhancer-fails-duplicates.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/eclipse/eclipse-200-enhancer-fails-duplicates.png
deleted file mode 100644
index 8d7e10a..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/eclipse/eclipse-200-enhancer-fails-duplicates.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/eclipse/eclipse-210-enhancer-fails-duplicates.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/eclipse/eclipse-210-enhancer-fails-duplicates.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/eclipse/eclipse-210-enhancer-fails-duplicates.png
deleted file mode 100644
index 5350251..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/eclipse/eclipse-210-enhancer-fails-duplicates.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/eclipse/eclipse-220-enhancer-fails-duplicates.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/eclipse/eclipse-220-enhancer-fails-duplicates.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/eclipse/eclipse-220-enhancer-fails-duplicates.png
deleted file mode 100644
index dbe247e..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/eclipse/eclipse-220-enhancer-fails-duplicates.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/010-installing/010-welcome-page.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/010-installing/010-welcome-page.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/010-installing/010-welcome-page.png
deleted file mode 100644
index 24fbed3..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/010-installing/010-welcome-page.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/010-installing/020-choose-location.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/010-installing/020-choose-location.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/010-installing/020-choose-location.png
deleted file mode 100644
index 1d0cb46..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/010-installing/020-choose-location.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/010-installing/030-installation-options.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/010-installing/030-installation-options.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/010-installing/030-installation-options.png
deleted file mode 100644
index 01fbe56..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/010-installing/030-installation-options.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/010-installing/040-start-menu-folder.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/010-installing/040-start-menu-folder.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/010-installing/040-start-menu-folder.png
deleted file mode 100644
index dc850cc..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/010-installing/040-start-menu-folder.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/010-installing/050-completing.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/010-installing/050-completing.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/010-installing/050-completing.png
deleted file mode 100644
index 7b80e17..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/010-installing/050-completing.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/010-installing/060-import-settings-or-not.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/010-installing/060-import-settings-or-not.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/010-installing/060-import-settings-or-not.png
deleted file mode 100644
index 0054c4c..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/010-installing/060-import-settings-or-not.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/010-installing/070-set-ui-theme.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/010-installing/070-set-ui-theme.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/010-installing/070-set-ui-theme.png
deleted file mode 100644
index 247fc64..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/010-installing/070-set-ui-theme.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/020-create-new-project/010-new-project-create.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/020-create-new-project/010-new-project-create.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/020-create-new-project/010-new-project-create.png
deleted file mode 100644
index a950887..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/020-create-new-project/010-new-project-create.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/020-create-new-project/020-java-project-setup-jdk.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/020-create-new-project/020-java-project-setup-jdk.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/020-create-new-project/020-java-project-setup-jdk.png
deleted file mode 100644
index 16fe8d1..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/020-create-new-project/020-java-project-setup-jdk.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/020-create-new-project/030-java-project-select-jdk.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/020-create-new-project/030-java-project-select-jdk.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/020-create-new-project/030-java-project-select-jdk.png
deleted file mode 100644
index d0214c6..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/020-create-new-project/030-java-project-select-jdk.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/020-create-new-project/040-sdk-selected.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/020-create-new-project/040-sdk-selected.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/020-create-new-project/040-sdk-selected.png
deleted file mode 100644
index b9399d6..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/020-create-new-project/040-sdk-selected.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/020-create-new-project/050-name-and-location.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/020-create-new-project/050-name-and-location.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/020-create-new-project/050-name-and-location.png
deleted file mode 100644
index 7f3b8d6..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/020-create-new-project/050-name-and-location.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/020-create-new-project/060-create-dir.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/020-create-new-project/060-create-dir.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/020-create-new-project/060-create-dir.png
deleted file mode 100644
index 287478a..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/020-create-new-project/060-create-dir.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/030-import-settings/010-settings-import-jar.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/030-import-settings/010-settings-import-jar.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/030-import-settings/010-settings-import-jar.png
deleted file mode 100644
index be6fb1e..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/030-import-settings/010-settings-import-jar.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/030-import-settings/020-select-all.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/030-import-settings/020-select-all.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/030-import-settings/020-select-all.png
deleted file mode 100644
index 8e63a35..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/030-import-settings/020-select-all.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/030-import-settings/030-restart.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/030-import-settings/030-restart.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/030-import-settings/030-restart.png
deleted file mode 100644
index c20e0ac..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/030-import-settings/030-restart.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/030-import-settings/040-file-templates.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/030-import-settings/040-file-templates.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/030-import-settings/040-file-templates.png
deleted file mode 100644
index c238509..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/030-import-settings/040-file-templates.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/030-import-settings/050-live-templates.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/030-import-settings/050-live-templates.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/030-import-settings/050-live-templates.png
deleted file mode 100644
index 6fc56ba..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/030-import-settings/050-live-templates.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/040-other-settings-compiler/010-build-automatically.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/040-other-settings-compiler/010-build-automatically.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/040-other-settings-compiler/010-build-automatically.png
deleted file mode 100644
index b383b3c..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/040-other-settings-compiler/010-build-automatically.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/040-other-settings-compiler/020-annotation-processor.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/040-other-settings-compiler/020-annotation-processor.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/040-other-settings-compiler/020-annotation-processor.png
deleted file mode 100644
index 7618a4d..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/040-other-settings-compiler/020-annotation-processor.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/042-other-settings-maven/010-maven-installation.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/042-other-settings-maven/010-maven-installation.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/042-other-settings-maven/010-maven-installation.png
deleted file mode 100644
index 9fef693..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/042-other-settings-maven/010-maven-installation.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/042-other-settings-maven/020-maven-configuration.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/042-other-settings-maven/020-maven-configuration.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/042-other-settings-maven/020-maven-configuration.png
deleted file mode 100644
index 945968d..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/042-other-settings-maven/020-maven-configuration.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/044-other-settings-misc/010-auto-import.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/044-other-settings-misc/010-auto-import.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/044-other-settings-misc/010-auto-import.png
deleted file mode 100644
index 293d2c3..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/044-other-settings-misc/010-auto-import.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/050-some-plugins/010-some-plugins.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/050-some-plugins/010-some-plugins.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/050-some-plugins/010-some-plugins.png
deleted file mode 100644
index 9e2230b..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/050-some-plugins/010-some-plugins.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/050-some-plugins/020-some-plugins-confirmation.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/050-some-plugins/020-some-plugins-confirmation.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/050-some-plugins/020-some-plugins-confirmation.png
deleted file mode 100644
index 037c967..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/050-some-plugins/020-some-plugins-confirmation.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/010-dependency-tab.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/010-dependency-tab.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/010-dependency-tab.png
deleted file mode 100644
index a42b430..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/010-dependency-tab.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/020-dependency-as-tree.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/020-dependency-as-tree.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/020-dependency-as-tree.png
deleted file mode 100644
index 15ae90b..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/020-dependency-as-tree.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/030-maven-run-goal.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/030-maven-run-goal.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/030-maven-run-goal.png
deleted file mode 100644
index e8a6d1e..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/030-maven-run-goal.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/040-maven-quick-run.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/040-maven-quick-run.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/040-maven-quick-run.png
deleted file mode 100644
index f3a6d67..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/050-some-plugins/maven-helper/040-maven-quick-run.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/060-troubleshooting/010-duplicate-classes.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/060-troubleshooting/010-duplicate-classes.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/060-troubleshooting/010-duplicate-classes.png
deleted file mode 100644
index 1d6d6c3..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/060-troubleshooting/010-duplicate-classes.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/070-advanced/002-compiler-exclude.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/070-advanced/002-compiler-exclude.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/070-advanced/002-compiler-exclude.png
deleted file mode 100644
index ba9cb59..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/070-advanced/002-compiler-exclude.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/070-advanced/004-gradle-output.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/070-advanced/004-gradle-output.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/070-advanced/004-gradle-output.png
deleted file mode 100644
index 023538d..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/070-advanced/004-gradle-output.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/070-advanced/005-gradle-output.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/070-advanced/005-gradle-output.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/070-advanced/005-gradle-output.png
deleted file mode 100644
index edaa8e5..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/070-advanced/005-gradle-output.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/070-advanced/006-livereload-js.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/070-advanced/006-livereload-js.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/070-advanced/006-livereload-js.png
deleted file mode 100644
index f5d6a2b..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/070-advanced/006-livereload-js.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/070-advanced/010-dcevm-list-of-found-jdk-installations.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/070-advanced/010-dcevm-list-of-found-jdk-installations.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/070-advanced/010-dcevm-list-of-found-jdk-installations.png
deleted file mode 100644
index 601e418..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/070-advanced/010-dcevm-list-of-found-jdk-installations.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/070-advanced/020-dcevm-once-installed.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/070-advanced/020-dcevm-once-installed.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/070-advanced/020-dcevm-once-installed.png
deleted file mode 100644
index afc39ea..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/070-advanced/020-dcevm-once-installed.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/070-advanced/030-dcevm-intellij-project-structure.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/070-advanced/030-dcevm-intellij-project-structure.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/070-advanced/030-dcevm-intellij-project-structure.png
deleted file mode 100644
index 951b4a6..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/070-advanced/030-dcevm-intellij-project-structure.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/070-advanced/040-dcevm-run-configuration.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/070-advanced/040-dcevm-run-configuration.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/070-advanced/040-dcevm-run-configuration.png
deleted file mode 100644
index 9d042f7..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/070-advanced/040-dcevm-run-configuration.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/010-maven-modules-view.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/010-maven-modules-view.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/010-maven-modules-view.png
deleted file mode 100644
index a5b8944..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/010-maven-modules-view.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/020-adding-another-module.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/020-adding-another-module.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/020-adding-another-module.png
deleted file mode 100644
index b8e9ba9..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/020-adding-another-module.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/030-other-module-added.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/030-other-module-added.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/030-other-module-added.png
deleted file mode 100644
index 58b42f0..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/030-other-module-added.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/040-ignoring-modules.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/040-ignoring-modules.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/040-ignoring-modules.png
deleted file mode 100644
index 0421f99..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/040-ignoring-modules.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/050-ignoring-modules-2.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/050-ignoring-modules-2.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/050-ignoring-modules-2.png
deleted file mode 100644
index 6bf26ac..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/050-ignoring-modules-2.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/060-ignored-modules.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/060-ignored-modules.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/060-ignored-modules.png
deleted file mode 100644
index b16086b..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/060-ignored-modules.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/110-running-the-app/010-run-configuration.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/110-running-the-app/010-run-configuration.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/110-running-the-app/010-run-configuration.png
deleted file mode 100644
index 0c6a929..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/110-running-the-app/010-run-configuration.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/110-running-the-app/020-datanucleus-enhancer-goal.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/110-running-the-app/020-datanucleus-enhancer-goal.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/110-running-the-app/020-datanucleus-enhancer-goal.png
deleted file mode 100644
index 2dae157..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/110-running-the-app/020-datanucleus-enhancer-goal.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/110-running-the-app/030-running-unit-tests.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/110-running-the-app/030-running-unit-tests.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/110-running-the-app/030-running-unit-tests.png
deleted file mode 100644
index b4e042a..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/110-running-the-app/030-running-unit-tests.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/110-running-the-app/040-running-unit-tests-run-configuration.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/110-running-the-app/040-running-unit-tests-run-configuration.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/110-running-the-app/040-running-unit-tests-run-configuration.png
deleted file mode 100644
index 83a4a70..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/110-running-the-app/040-running-unit-tests-run-configuration.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/110-running-the-app/050-running-integration-tests-run-configuration.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/110-running-the-app/050-running-integration-tests-run-configuration.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/110-running-the-app/050-running-integration-tests-run-configuration.png
deleted file mode 100644
index 6b0ad89..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/110-running-the-app/050-running-integration-tests-run-configuration.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/200-project-sdk/010-file-project-structure.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/200-project-sdk/010-file-project-structure.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/200-project-sdk/010-file-project-structure.png
deleted file mode 100644
index 544a185..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/200-project-sdk/010-file-project-structure.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/200-project-sdk/020-select-jdk.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/200-project-sdk/020-select-jdk.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/200-project-sdk/020-select-jdk.png
deleted file mode 100644
index 90865f1..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/200-project-sdk/020-select-jdk.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/200-project-sdk/030-select-jdk-directory.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/200-project-sdk/030-select-jdk-directory.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/200-project-sdk/030-select-jdk-directory.png
deleted file mode 100644
index f5675b2..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/200-project-sdk/030-select-jdk-directory.png and /dev/null differ

[10/58] [abbrv] isis git commit: ISIS-1521: fixes xref links between guides

[da...@apache.org]

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcfg/_rgcfg_specifying-components.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcfg/_rgcfg_specifying-components.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcfg/_rgcfg_specifying-components.adoc
index 7bb3fe2..00af60a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcfg/_rgcfg_specifying-components.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcfg/_rgcfg_specifying-components.adoc
@@ -11,7 +11,7 @@ Bootstrapping an Apache Isis application involves identifying both:
 * the major components (authentication, persistence mechanisms, viewers) of Apache Isis, and also
 * specifying the domain services and persistent entities that make up the application itself.
 
-As of 1.9.0 there are two different ways to perform this bootstrapping.  The recommended (newer) approach is to use an xref:rgcms.adoc#_rgcms_classes_super_AppManifest[`AppManifest`], specified either programmatically or through the configuration properties.  This allows the components, services and entities to be specified from a single class.  The alternative (and older, pre 1.9.0) approach is to specify this information individually, through configuration properties.
+As of 1.9.0 there are two different ways to perform this bootstrapping.  The recommended (newer) approach is to use an xref:../rgcms/rgcms.adoc#_rgcms_classes_super_AppManifest[`AppManifest`], specified either programmatically or through the configuration properties.  This allows the components, services and entities to be specified from a single class.  The alternative (and older, pre 1.9.0) approach is to specify this information individually, through configuration properties.
 
 To specify the `AppManifest` as a configuration property, use:
 
@@ -27,7 +27,7 @@ To specify the `AppManifest` as a configuration property, use:
 |`FQCN`
 |`o.a.i.applib.AppManifest` +
 
-By convention this implementation resides in an `myapp-app` Maven module (as opposed to `myapp-dom` or `myapp-fixture`).  See the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] for details.
+By convention this implementation resides in an `myapp-app` Maven module (as opposed to `myapp-dom` or `myapp-fixture`).  See the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] for details.
 
 |===
 
@@ -49,7 +49,7 @@ If the `AppManifest` approach is _not_ being used, then the following configurat
 (`_shiro_`)
 |`o.a.i.core.runtime.authentication.` `AuthenticationManagerInstaller` +
 
-This property is IGNORED if the `isis.appManifest` configuration property is specified, or if an xref:rgcms.adoc#_rgcms_classes_super_AppManifest[`AppManifest`] is provided programmatically.
+This property is IGNORED if the `isis.appManifest` configuration property is specified, or if an xref:../rgcms/rgcms.adoc#_rgcms_classes_super_AppManifest[`AppManifest`] is provided programmatically.
 
 
 |`isis.authorization`
@@ -57,7 +57,7 @@ This property is IGNORED if the `isis.appManifest` configuration property is spe
 (`_shiro_`)
 |`o.a.i.core.runtime.authorization.` `AuthorizationManagerInstaller` +
 
-This property is IGNORED if the `isis.appManifest` configuration property is specified, or if an xref:rgcms.adoc#_rgcms_classes_super_AppManifest[`AppManifest`] is provided programmatically.
+This property is IGNORED if the `isis.appManifest` configuration property is specified, or if an xref:../rgcms/rgcms.adoc#_rgcms_classes_super_AppManifest[`AppManifest`] is provided programmatically.
 
 |`isis.persistor`
 |`datanucleus`
@@ -80,7 +80,7 @@ The mechanism to discover and load domain services:
 
 * Otherwise an alternative implementation of the `o.a.i.core.runtime.services.ServicesInstaller` internal API can be provided. +
 
-This property is IGNORED if the `isis.appManifest` configuration property is specified, or if an xref:rgcms.adoc#_rgcms_classes_super_AppManifest[`AppManifest`] is provided programmatically.
+This property is IGNORED if the `isis.appManifest` configuration property is specified, or if an xref:../rgcms/rgcms.adoc#_rgcms_classes_super_AppManifest[`AppManifest`] is provided programmatically.
 
 This property is also IGNORED completely in 1.13.0+; the `configuration-and-annotation` implementation is always used.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes.adoc
index 3cb8b4f..213d973 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-This chapter describes the usage of various classes and interfaces that are not otherwise associated with xref:rgsvc.adoc[domain services], xref:ugvw.adoc#_ugvw_layout[object layout] or xref:rgcfg.adoc#_rgcfg[configuration].
+This chapter describes the usage of various classes and interfaces that are not otherwise associated with xref:../rgsvc/rgsvc.adoc[domain services], xref:ugvw.adoc#_ugvw_layout[object layout] or xref:../rgcfg/rgcfg.adoc#_rgcfg[configuration].
 
 
 include::_rgcms_classes_AppManifest-bootstrapping.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_AppManifest-bootstrapping.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_AppManifest-bootstrapping.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_AppManifest-bootstrapping.adoc
index ca292de..d80fd36 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_AppManifest-bootstrapping.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_AppManifest-bootstrapping.adoc
@@ -39,7 +39,7 @@ The following sections describe each of these methods in a little more detail.
 
 === `getModules()`
 
-The most significant method (the only one which must return a non-`null` value) is the `getModules()` method.  Each module is identified by a class; the framework simply uses that class' package as the root to search for domain services (annotated with xref:rgant.adoc#_rgant-DomainService[`@DomainService`]) and entities (annotated with xref:rgant.adoc#_rgant-PersistenceCapable[`@PersistenceCapable`]).  Generally there is one such module class per Maven module.
+The most significant method (the only one which must return a non-`null` value) is the `getModules()` method.  Each module is identified by a class; the framework simply uses that class' package as the root to search for domain services (annotated with xref:../rgant/rgant.adoc#_rgant-DomainService[`@DomainService`]) and entities (annotated with xref:../rgant/rgant.adoc#_rgant-PersistenceCapable[`@PersistenceCapable`]).  Generally there is one such module class per Maven module.
 
 A module class for a domain module might for example be defined as:
 
@@ -82,7 +82,7 @@ As can be seen, the various (non-ASF) link:http://isisaddons.org[Isis Addons] mo
 
 === `getAdditionalServices()`
 
-We normally we recommend that services are defined exclusively through `getModules()`, and that this method should therefore return an empty list.  However, there are certain use cases where the a service must be explicitly specified either because the service required does not (for whatever reason) have a xref:rgant.adoc#_rgant-DomainService[`@DomainService`] annotation.
+We normally we recommend that services are defined exclusively through `getModules()`, and that this method should therefore return an empty list.  However, there are certain use cases where the a service must be explicitly specified either because the service required does not (for whatever reason) have a xref:../rgant/rgant.adoc#_rgant-DomainService[`@DomainService`] annotation.
 
 For example, the (non-ASF) http://github.com/isisaddons/isis-module-security[Isis addons' security] module (v1.9.0) allows the policy to evaluate conflicting permissions to be specified by explicitly registering either the `PermissionsEvaluationServiceAllowBeatsVeto` domain service or the `PermissionsEvaluationServiceVetoBeatsAllow` domain service:
 
@@ -208,7 +208,7 @@ public interface AppManifest {
 (disable persistence by reachability, support mixed case identifiers, disable level 2 cache)
 <3> sets up standard properties for the Apache Isis framework, most specifically to enable fixtures to be installed.
 
-For example, the bootstrapping code for the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] looks something like:
+For example, the bootstrapping code for the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] looks something like:
 
 [source,java]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_contributee_HasTransactionId.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_contributee_HasTransactionId.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_contributee_HasTransactionId.adoc
index 59cde44..6b825c5 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_contributee_HasTransactionId.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_contributee_HasTransactionId.adoc
@@ -6,7 +6,7 @@
 
 
 The `HasTransactionId` interface is a mix-in for any domain objects that reference a transaction id, such as
-auditing entries or commands, or for xref:rgsvc.adoc#_rgsvc_api_InteractionContext[``Interaction``]s persisted as
+auditing entries or commands, or for xref:../rgsvc/rgsvc.adoc#_rgsvc_api_InteractionContext[``Interaction``]s persisted as
 published events.
 
 [NOTE]

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_domainevent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_domainevent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_domainevent.adoc
index d7a1586..bc18d88 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_domainevent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_domainevent.adoc
@@ -7,8 +7,8 @@
 
 This section catalogues the various domain event classes defined by Apache Isis.
 
-These events are broadcast on the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`].  The domain
-events are broadcast as a result of being specified in the xref:rgant.adoc#_rgant-Action_domainEvent[`@Action#domainEvent()`],  xref:rgant.adoc#_rgant-Property_domainEvent[`@Property#domainEvent()`] or xref:rgant.adoc#_rgant-Collection_domainEvent[`@Collection#domainEvent()`] attributes.
+These events are broadcast on the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`].  The domain
+events are broadcast as a result of being specified in the xref:../rgant/rgant.adoc#_rgant-Action_domainEvent[`@Action#domainEvent()`],  xref:../rgant/rgant.adoc#_rgant-Property_domainEvent[`@Property#domainEvent()`] or xref:../rgant/rgant.adoc#_rgant-Collection_domainEvent[`@Collection#domainEvent()`] attributes.
 
 They are listed in the table below.
 
@@ -23,7 +23,7 @@ Impl'n (g: a:)
 |Notes
 
 
-|xref:rgcms.adoc#_rgcms_classes_domainevent_AbstractDomainEvent[`o.a.i.applib.` +
+|xref:../rgcms/rgcms.adoc#_rgcms_classes_domainevent_AbstractDomainEvent[`o.a.i.applib.` +
 `AbstractDomainEvent`]
 |``o.a.i.core`` +
 ``services.eventbus`` +
@@ -32,7 +32,7 @@ Impl'n (g: a:)
 |Superclass of the other domain events, listed below in this table.
 
 
-|xref:rgcms.adoc#_rgcms_classes_domainevent_ActionDomainEvent[`o.a.i.applib.` +
+|xref:../rgcms/rgcms.adoc#_rgcms_classes_domainevent_ActionDomainEvent[`o.a.i.applib.` +
 `ActionDomainEvent`]
 |``o.a.i.core`` +
 ``services.eventbus`` +
@@ -42,7 +42,7 @@ Impl'n (g: a:)
 |Broadcast whenever there is an interaction (hide/disable/validate/pre-execute/post-execute) with an object's action.
 
 
-|xref:rgcms.adoc#_rgcms_classes_domainevent_CollectionDomainEvent[`o.a.i.applib.` +
+|xref:../rgcms/rgcms.adoc#_rgcms_classes_domainevent_CollectionDomainEvent[`o.a.i.applib.` +
 `CollectionDomainEvent`]
 |``o.a.i.core`` +
 ``services.eventbus`` +
@@ -53,7 +53,7 @@ is specified.
 |Broadcast whenever there is an interaction (hide/disable/validate/access) with an object's collection.
 
 
-|xref:rgcms.adoc#_rgcms_classes_domainevent_PropertyDomainEvent[`o.a.i.applib.` +
+|xref:../rgcms/rgcms.adoc#_rgcms_classes_domainevent_PropertyDomainEvent[`o.a.i.applib.` +
 `PropertyDomainEvent`]
 |``o.a.i.core`` +
 ``services.eventbus`` +

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_domainevent_AbstractDomainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_domainevent_AbstractDomainEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_domainevent_AbstractDomainEvent.adoc
index 7740763..2828b89 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_domainevent_AbstractDomainEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_domainevent_AbstractDomainEvent.adoc
@@ -10,11 +10,11 @@ properties or collections.
 
 Its immediate subclasses are:
 
-* xref:rgcms.adoc#_rgcms_classes_domainevent_ActionDomainEvent[`ActionDomainEvent`]
+* xref:../rgcms/rgcms.adoc#_rgcms_classes_domainevent_ActionDomainEvent[`ActionDomainEvent`]
 
-* xref:rgcms.adoc#_rgcms_classes_domainevent_PropertyDomainEvent[`PropertyDomainEvent`]
+* xref:../rgcms/rgcms.adoc#_rgcms_classes_domainevent_PropertyDomainEvent[`PropertyDomainEvent`]
 
-* xref:rgcms.adoc#_rgcms_classes_domainevent_CollectionDomainEvent[`CollectionDomainEvent`]
+* xref:../rgcms/rgcms.adoc#_rgcms_classes_domainevent_CollectionDomainEvent[`CollectionDomainEvent`]
 
 The main purpose of the class is to define the protocol by which subscribers can influence an interaction (eg hide a
 collection, disable a property, validate action arguments).  It class also provides a simple mechanism to allow

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_domainevent_ActionDomainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_domainevent_ActionDomainEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_domainevent_ActionDomainEvent.adoc
index 8b0713e..05a3ef9 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_domainevent_ActionDomainEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_domainevent_ActionDomainEvent.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-Subclass of xref:rgcms.adoc#_rgcms_classes_domainevent_AbstractDomainEvent[`AbstractDomainEvent`] for actions.
+Subclass of xref:../rgcms/rgcms.adoc#_rgcms_classes_domainevent_AbstractDomainEvent[`AbstractDomainEvent`] for actions.
 
 The class has a number of responsibilities (in addition to those it inherits):
 
@@ -15,7 +15,7 @@ The class has a number of responsibilities (in addition to those it inherits):
 
 * provide selected metadata about the action parameters from the metamodel (names, types)
 
-* link back to the xref:rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`] service's `Command` object
+* link back to the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`] service's `Command` object
 
 The class itself is instantiated automatically by the framework whenever interacting with a rendered object's action.
 
@@ -44,12 +44,12 @@ public abstract class ActionDomainEvent<S> extends AbstractDomainEvent<S> {
     public Object getReturnValue();                                         // <7>
 }
 ----
-<1> The `Default` nested static class is the default for the xref:rgant.adoc#_rgant_Action_domainEvent[`@Action#domainEvent()`]
+<1> The `Default` nested static class is the default for the xref:../rgant/rgant.adoc#_rgant_Action_domainEvent[`@Action#domainEvent()`]
 annotation attribute.  Whether this raises an event or not depends upon the
 `isis.reflector.facet.actionAnnotation.domainEvent.postForDefault` configuration property.
 <2> The `Noop` class is provided as a convenience to indicate that an event should _not_ be posted (irrespective of the configuration property setting).
 <3> Similarly, the `Doop` class is provided as a convenience to indicate that an event _should_ be raised (irrespective of the configuration property setting).
-<4> Deprecated, use xref:rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`] or (better)  xref:rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`]instead.
+<4> Deprecated, use xref:../rgsvc/rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`] or (better)  xref:../rgsvc/rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`]instead.
 <5> Populated only for mixins; holds the underlying domain object that the mixin contributes to.
 <6> The arguments being used to invoke the action; populated during validate phase and subsequent phases.
 <7> The value returned by the action; populated only in the executed phase.

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_domainevent_CollectionDomainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_domainevent_CollectionDomainEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_domainevent_CollectionDomainEvent.adoc
index f96bb4a..a258cfa 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_domainevent_CollectionDomainEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_domainevent_CollectionDomainEvent.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-Subclass of xref:rgcms.adoc#_rgcms_classes_domainevent_AbstractDomainEvent[`AbstractDomainEvent`] for collections.
+Subclass of xref:../rgcms/rgcms.adoc#_rgcms_classes_domainevent_AbstractDomainEvent[`AbstractDomainEvent`] for collections.
 
 The class has a couple of responsibilities (in addition to those it inherits):
 
@@ -38,7 +38,7 @@ public abstract class CollectionDomainEvent<S,T> extends AbstractDomainEvent<S>
     public Of getOf();                                          // <5>
 }
 ----
-<1> The `Default` nested static class is the default for the xref:rgant.adoc#_rgant_Collection_domainEvent[`@Collection#domainEvent()`]
+<1> The `Default` nested static class is the default for the xref:../rgant/rgant.adoc#_rgant_Collection_domainEvent[`@Collection#domainEvent()`]
 annotation attribute.  Whether this raises an event or not depends upon the
 `isis.reflector.facet.collectionAnnotation.domainEvent.postForDefault` configuration property.
 <2> The `Noop` class is provided as a convenience to indicate that an event should _not_ be posted (irrespective of the configuration property setting).

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_domainevent_PropertyDomainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_domainevent_PropertyDomainEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_domainevent_PropertyDomainEvent.adoc
index e6649ff..a2d16b5 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_domainevent_PropertyDomainEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_domainevent_PropertyDomainEvent.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-Subclass of xref:rgcms.adoc#_rgcms_classes_domainevent_AbstractDomainEvent[`AbstractDomainEvent`] for properties.
+Subclass of xref:../rgcms/rgcms.adoc#_rgcms_classes_domainevent_AbstractDomainEvent[`AbstractDomainEvent`] for properties.
 
 The class has a couple of responsibilities (in addition to those it inherits):
 
@@ -36,7 +36,7 @@ public abstract class PropertyDomainEvent<S,T> extends AbstractDomainEvent<S> {
     public T getNewValue();                                     // <5>
 }
 ----
-<1> The `Default` nested static class is the default for the xref:rgant.adoc#_rgant_Property_domainEvent[`@Property#domainEvent()`]
+<1> The `Default` nested static class is the default for the xref:../rgant/rgant.adoc#_rgant_Property_domainEvent[`@Property#domainEvent()`]
 annotation attribute.  Whether this raises an event or not depends upon the
 `isis.reflector.facet.propertyAnnotation.domainEvent.postForDefault` configuration property.
 <2> The `Noop` class is provided as a convenience to indicate that an event should _not_ be posted (irrespective of the configuration property setting).

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_layout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_layout.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_layout.adoc
index f8d3734..bcd821d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_layout.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_layout.adoc
@@ -15,9 +15,9 @@ The `org.apache.isis.applib.layout` package defines a number of classes that all
 The framework provides an implementation of the grid classes modelled closely on link:http://getbootstrap.com[Bootstrap 3], along with xref:ugvw.adoc[Wicket viewer] components capable of rendering that grid system.  In principle it is
 also possible to extend the layout architecture for other grid systems.  The component classes, though, are intended to be reusable across all grid systems.
 
-The component classes, meanwhile, are broadly equivalent to the "layout" annotations (xref:rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`], xref:rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`], xref:rgant.adoc#_rgant-ActionLayout[`@ActionLayout`] and xref:rgant.adoc#_rgant-DomainObjectLayout[`@DomainObjectLayout`]
+The component classes, meanwhile, are broadly equivalent to the "layout" annotations (xref:../rgant/rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`], xref:../rgant/rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`], xref:../rgant/rgant.adoc#_rgant-ActionLayout[`@ActionLayout`] and xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout[`@DomainObjectLayout`]
 
-All of the classes in this package are JAXB-annotated, meaning that they can be serialized to/from XML (the `component` classes in the `http://isis.apache.org/applib/layout/component` XSD namespace, the bootstrap 3 grid classes in the `http://isis.apache.org/applib/layout/grid/bootstrap3` XSD namespace).  This ability to serialize to/from XML is used by the xref:rgsvc.adoc#_rgsvc_spi_GridLoaderService[`GridLoaderService`], the default implementation of which reads the grid layout for a domain class from a `.layout.xml` file on the classpath.
+All of the classes in this package are JAXB-annotated, meaning that they can be serialized to/from XML (the `component` classes in the `http://isis.apache.org/applib/layout/component` XSD namespace, the bootstrap 3 grid classes in the `http://isis.apache.org/applib/layout/grid/bootstrap3` XSD namespace).  This ability to serialize to/from XML is used by the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_GridLoaderService[`GridLoaderService`], the default implementation of which reads the grid layout for a domain class from a `.layout.xml` file on the classpath.
 
 
 
@@ -33,13 +33,13 @@ A fieldset (previously also called a property group or member group) of a number
 
 * layout data classes, which correspond to the similarly named annotations:
 
-** `PropertyLayoutData`, corresponding to the xref:rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`] annotation;
+** `PropertyLayoutData`, corresponding to the xref:../rgant/rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`] annotation;
 
-** `CollectionLayoutData`, corresponding to the xref:rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`] annotation;
+** `CollectionLayoutData`, corresponding to the xref:../rgant/rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`] annotation;
 
-** `ActionLayoutData`, corresponding to the xref:rgant.adoc#_rgant-ActionLayout[`@ActionLayout`] annotation;
+** `ActionLayoutData`, corresponding to the xref:../rgant/rgant.adoc#_rgant-ActionLayout[`@ActionLayout`] annotation;
 
-** `DomainObjectLayoutData`, corresponding to the xref:rgant.adoc#_rgant-DomainObjectLayout[`@DomainObjectLayout`] annotation.
+** `DomainObjectLayoutData`, corresponding to the xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout[`@DomainObjectLayout`] annotation.
 
 In addition, the component package includes `Grid`, representing the top level container for a custom layout for a domain object.  `Grid` itself is merely an interface, but it also defines the visitor pattern to make it easy for validate and normalize the grid layouts.  The `GridAbstract` convenience superclass provides a partial implementation of this visitor pattern.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_lifecycleevent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_lifecycleevent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_lifecycleevent.adoc
index a16eb73..e01f067 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_lifecycleevent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_lifecycleevent.adoc
@@ -22,7 +22,7 @@ Impl'n (g: a:)
 |Notes
 
 
-|xref:rgcms.adoc#_rgcms_classes_lifecycleevent_AbstractLifecycleEvent[`o.a.i.applib.` +
+|xref:../rgcms/rgcms.adoc#_rgcms_classes_lifecycleevent_AbstractLifecycleEvent[`o.a.i.applib.` +
 `AbstractLifecycleEvent`]
 |``o.a.i.core`` +
 ``services.eventbus`` +
@@ -31,7 +31,7 @@ Impl'n (g: a:)
 |Superclass of the other lifecycle events, listed below in this table.
 
 
-|xref:rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectCreatedDomainEvent[`o.a.i.applib.` +
+|xref:../rgcms/rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectCreatedDomainEvent[`o.a.i.applib.` +
 `ObjectCreatedEvent`]
 |``o.a.i.core`` +
 ``services.eventbus`` +
@@ -39,11 +39,11 @@ Impl'n (g: a:)
 |(abstract class). +
 `ObjectCreatedEvent.Default` is the concrete implementation that is used.
 |Broadcast when an object is first instantiated
-using the xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-creation-api[`DomainObjectContainer`]'s
+using the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-creation-api[`DomainObjectContainer`]'s
 `#newTransientInstance(...)` method.
 
 
-|xref:rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectLoadedDomainEvent[`o.a.i.applib.` +
+|xref:../rgcms/rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectLoadedDomainEvent[`o.a.i.applib.` +
 `ObjectLoadedEvent`]
 |``o.a.i.core`` +
 ``services.eventbus`` +
@@ -53,7 +53,7 @@ using the xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-creation-api[`
 |Broadcast when an object is retrieved from the database.
 
 
-|xref:rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectPersistedDomainEvent[`o.a.i.applib.` +
+|xref:../rgcms/rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectPersistedDomainEvent[`o.a.i.applib.` +
 `ObjectPersistedEvent`]
 |``o.a.i.core`` +
 ``services.eventbus`` +
@@ -61,11 +61,11 @@ using the xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-creation-api[`
 |(abstract class). +
 `ObjectPersistedEvent.Default` is the concrete implementation that is used.
 |Broadcast when an object is first saved (inserted) into the database using the
-xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer`]'s
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer`]'s
 `#persist(...)` method.
 
 
-|xref:rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectPersistingDomainEvent[`o.a.i.applib.` +
+|xref:../rgcms/rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectPersistingDomainEvent[`o.a.i.applib.` +
 `ObjectPersistingEvent`]
 |``o.a.i.core`` +
 ``services.eventbus`` +
@@ -73,11 +73,11 @@ xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-persistence-api[`DomainO
 |(abstract class). +
 `ObjectPersistingEvent.Default` is the concrete implementation that is used.
 |Broadcast when an object is about to be saved (inserted) into the database using the
-xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer`]'s
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer`]'s
 `#persist(...)` method.
 
 
-|xref:rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectRemovingDomainEvent[`o.a.i.applib.` +
+|xref:../rgcms/rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectRemovingDomainEvent[`o.a.i.applib.` +
 `ObjectRemovingEvent`]
 |``o.a.i.core`` +
 ``services.eventbus`` +
@@ -85,11 +85,11 @@ xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-persistence-api[`DomainO
 |(abstract class). +
 `ObjectRemovingEvent.Default` is the concrete implementation that is used.
 |Broadcast when an object is about to be deleted from the database using the
-xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer`]'s
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer`]'s
 `#remove(...)` method.
 
 
-|xref:rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectUpdatedDomainEvent[`o.a.i.applib.` +
+|xref:../rgcms/rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectUpdatedDomainEvent[`o.a.i.applib.` +
 `ObjectUpdatedEvent`]
 |``o.a.i.core`` +
 ``services.eventbus`` +
@@ -98,11 +98,11 @@ xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-persistence-api[`DomainO
 `ObjectUpdatedEvent.Default` is the concrete implementation that is used.
 |Broadcast when an object has just been updated in the database.  This is done either explicitly when the current
 transaction is flushed using the
-xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer`]'s
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer`]'s
 `#flush(...)` method, else is done implicitly when the transaction commits at the end of the user request.
 
 
-|xref:rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectUpdatingDomainEvent[`o.a.i.applib.` +
+|xref:../rgcms/rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectUpdatingDomainEvent[`o.a.i.applib.` +
 `ObjectUpdatingEvent`]
 |``o.a.i.core`` +
 ``services.eventbus`` +
@@ -111,7 +111,7 @@ xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-persistence-api[`DomainO
 `ObjectUpdatingEvent.Default` is the concrete implementation that is used.
 |Broadcast when an object is about to be updated in the database.  This is done either explicitly when the current
 transaction is flushed using the
-xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer`]'s
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer`]'s
 `#flush(...)` method, else is done implicitly when the transaction commits at the end of the user request.
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_lifecycleevent_AbstractLifecycleEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_lifecycleevent_AbstractLifecycleEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_lifecycleevent_AbstractLifecycleEvent.adoc
index 92dd0d5..070e6d1 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_lifecycleevent_AbstractLifecycleEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_lifecycleevent_AbstractLifecycleEvent.adoc
@@ -10,18 +10,18 @@ or deleting objects from the database.
 
 Its immediate subclasses are:
 
-* xref:rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectCreatedEvent[`ObjectCreatedEvent`]
+* xref:../rgcms/rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectCreatedEvent[`ObjectCreatedEvent`]
 
-* xref:rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectLoadedEvent[`ObjectLoadedEvent`]
+* xref:../rgcms/rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectLoadedEvent[`ObjectLoadedEvent`]
 
-* xref:rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectPersistedEvent[`ObjectPersistedEvent`]
+* xref:../rgcms/rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectPersistedEvent[`ObjectPersistedEvent`]
 
-* xref:rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectPersistingEvent[`ObjectPersistingEvent`]
+* xref:../rgcms/rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectPersistingEvent[`ObjectPersistingEvent`]
 
-* xref:rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectRemovingEvent[`ObjectRemovingEvent`]
+* xref:../rgcms/rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectRemovingEvent[`ObjectRemovingEvent`]
 
-* xref:rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectUpdatedEvent[`ObjectUpdatedEvent`]
+* xref:../rgcms/rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectUpdatedEvent[`ObjectUpdatedEvent`]
 
-* xref:rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectUpdatingEvent[`ObjectUpdatingEvent`]
+* xref:../rgcms/rgcms.adoc#_rgcms_classes_lifecycleevent_ObjectUpdatingEvent[`ObjectUpdatingEvent`]
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_lifecycleevent_ObjectCreatedEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_lifecycleevent_ObjectCreatedEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_lifecycleevent_ObjectCreatedEvent.adoc
index 4aa52ad..3b1e931 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_lifecycleevent_ObjectCreatedEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_lifecycleevent_ObjectCreatedEvent.adoc
@@ -6,9 +6,9 @@
 
 
 
-Subclass of xref:rgcms.adoc#_rgcms_classes_lifecycleevent_AbstractLifecycleEvent[`AbstractLifecycleEvent`], broadcast
+Subclass of xref:../rgcms/rgcms.adoc#_rgcms_classes_lifecycleevent_AbstractLifecycleEvent[`AbstractLifecycleEvent`], broadcast
 when an object is first instantiated using the
-xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-creation-api[`DomainObjectContainer`]'s
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-creation-api[`DomainObjectContainer`]'s
 `#newTransientInstance(...)` method.
 
 `ObjectCreatedEvent.Default` is the concrete implementation that is used.

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_lifecycleevent_ObjectLoadedEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_lifecycleevent_ObjectLoadedEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_lifecycleevent_ObjectLoadedEvent.adoc
index ce7fb9a..8bcd12d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_lifecycleevent_ObjectLoadedEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_lifecycleevent_ObjectLoadedEvent.adoc
@@ -6,7 +6,7 @@
 
 
 
-Subclass of xref:rgcms.adoc#_rgcms_classes_lifecycleevent_AbstractLifecycleEvent[`AbstractLifecycleEvent`], broadcast
+Subclass of xref:../rgcms/rgcms.adoc#_rgcms_classes_lifecycleevent_AbstractLifecycleEvent[`AbstractLifecycleEvent`], broadcast
 when an object is retrieved from the database.
 
 `ObjectLoadedEvent.Default` is the concrete implementation that is used.

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_lifecycleevent_ObjectPersistedEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_lifecycleevent_ObjectPersistedEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_lifecycleevent_ObjectPersistedEvent.adoc
index d94f09c..179f65b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_lifecycleevent_ObjectPersistedEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_lifecycleevent_ObjectPersistedEvent.adoc
@@ -5,9 +5,9 @@
 :_imagesdir: images/
 
 
-Subclass of xref:rgcms.adoc#_rgcms_classes_lifecycleevent_AbstractLifecycleEvent[`AbstractLifecycleEvent`], broadcast
+Subclass of xref:../rgcms/rgcms.adoc#_rgcms_classes_lifecycleevent_AbstractLifecycleEvent[`AbstractLifecycleEvent`], broadcast
 when an object is first saved (inserted) into the database using the
-xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer`]'s
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer`]'s
 `#persist(...)` method.
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_lifecycleevent_ObjectPersistingEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_lifecycleevent_ObjectPersistingEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_lifecycleevent_ObjectPersistingEvent.adoc
index cc628df..7bde9cd 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_lifecycleevent_ObjectPersistingEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_lifecycleevent_ObjectPersistingEvent.adoc
@@ -5,9 +5,9 @@
 :_imagesdir: images/
 
 
-Subclass of xref:rgcms.adoc#_rgcms_classes_lifecycleevent_AbstractLifecycleEvent[`AbstractLifecycleEvent`], broadcast
+Subclass of xref:../rgcms/rgcms.adoc#_rgcms_classes_lifecycleevent_AbstractLifecycleEvent[`AbstractLifecycleEvent`], broadcast
 when an object is about to be saved (inserted) into the database using the
-xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer`]'s
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer`]'s
 `#persist(...)` method.
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_lifecycleevent_ObjectRemovingEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_lifecycleevent_ObjectRemovingEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_lifecycleevent_ObjectRemovingEvent.adoc
index 9e71dfb..263e7a0 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_lifecycleevent_ObjectRemovingEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_lifecycleevent_ObjectRemovingEvent.adoc
@@ -5,9 +5,9 @@
 :_imagesdir: images/
 
 
-Subclass of xref:rgcms.adoc#_rgcms_classes_lifecycleevent_AbstractLifecycleEvent[`AbstractLifecycleEvent`], broadcast
+Subclass of xref:../rgcms/rgcms.adoc#_rgcms_classes_lifecycleevent_AbstractLifecycleEvent[`AbstractLifecycleEvent`], broadcast
 when an object is about to be deleted from the database using the
-xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer`]'s
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer`]'s
 `#remove(...)` method.
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_lifecycleevent_ObjectUpdatedEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_lifecycleevent_ObjectUpdatedEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_lifecycleevent_ObjectUpdatedEvent.adoc
index 5963c12..862c104 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_lifecycleevent_ObjectUpdatedEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_lifecycleevent_ObjectUpdatedEvent.adoc
@@ -6,10 +6,10 @@
 
 
 
-Subclass of xref:rgcms.adoc#_rgcms_classes_lifecycleevent_AbstractLifecycleEvent[`AbstractLifecycleEvent`], broadcast
+Subclass of xref:../rgcms/rgcms.adoc#_rgcms_classes_lifecycleevent_AbstractLifecycleEvent[`AbstractLifecycleEvent`], broadcast
 when an object has just been updated in the database.  This is done either explicitly when the current
 transaction is flushed using the
-xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer`]'s
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer`]'s
 `#flush(...)` method, else is done implicitly when the transaction commits at the end of the user request.
 
 `ObjectUpdatedEvent.Default` is the concrete implementation that is used.

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_lifecycleevent_ObjectUpdatingEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_lifecycleevent_ObjectUpdatingEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_lifecycleevent_ObjectUpdatingEvent.adoc
index 65edd94..abfdd3d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_lifecycleevent_ObjectUpdatingEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_lifecycleevent_ObjectUpdatingEvent.adoc
@@ -6,10 +6,10 @@
 
 
 
-Subclass of xref:rgcms.adoc#_rgcms_classes_lifecycleevent_AbstractLifecycleEvent[`AbstractLifecycleEvent`], broadcast
+Subclass of xref:../rgcms/rgcms.adoc#_rgcms_classes_lifecycleevent_AbstractLifecycleEvent[`AbstractLifecycleEvent`], broadcast
 when an object is about to be updated in the database.  This is done either explicitly when the current
 transaction is flushed using the
-xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer`]'s
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer`]'s
 `#flush(...)` method, else is done implicitly when the transaction commits at the end of the user request.
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_mixins_Dto.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_mixins_Dto.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_mixins_Dto.adoc
index 3f019a6..9c4585a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_mixins_Dto.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_mixins_Dto.adoc
@@ -6,7 +6,7 @@
 
 
 The `Dto` role interface is intended to be implemented by JAXB-annotated view models, that is, annotated using
-xref:rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`].  It enables the ability to download the XML and
+xref:../rgant/rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`].  It enables the ability to download the XML and
 XSD schema of those objects using two xref:ugbtb.adoc#_ugbtb_decoupling_mixins[mixins],
 `Dto_downloadXml` and `Dto_downloadXsd`.
 
@@ -32,7 +32,7 @@ public class Dto_downloadXml {
 <2> actually this method is called '$$' in the code, a "special case" that means to use the derive the action name
 from the class name.
 
-This will return the XML text wrapped up in a xref:rgcms.adoc#_rgcms_classes_value-types_Clob[`Clob`].
+This will return the XML text wrapped up in a xref:../rgcms/rgcms.adoc#_rgcms_classes_value-types_Clob[`Clob`].
 
 The `Dto_downloadXsd` mixin is similar:
 
@@ -48,10 +48,10 @@ public class Dto_downloadXsd {
 <2> actually this is '$$' in the code, a "special case" that means to use the derive the action name from the class name.
 
 If the domain object's JAXB annotations reference only a single XSD schema then this will return that XML text as
-a xref:rgcms.adoc#_rgcms_classes_value-types_Clob[`Clob`] of that XSD.  If there are multiple XSD schemas referenced
+a xref:../rgcms/rgcms.adoc#_rgcms_classes_value-types_Clob[`Clob`] of that XSD.  If there are multiple XSD schemas referenced
 then the action will return a zip of those schemas, wrapped up in a
-xref:rgcms.adoc#_rgcms_classes_value-types_Blob[`Blob`].  The `IsisSchemas` parameter to the action can be used to
-optionally ignore the common xref:rgcms.adoc#_rgcms_schema[Apache Isis schemas] (useful if there is only one other XSD schema
+xref:../rgcms/rgcms.adoc#_rgcms_classes_value-types_Blob[`Blob`].  The `IsisSchemas` parameter to the action can be used to
+optionally ignore the common xref:../rgcms/rgcms.adoc#_rgcms_schema[Apache Isis schemas] (useful if there is only one other XSD schema
 referenced by the DTO).
 
 
@@ -59,4 +59,4 @@ referenced by the DTO).
 == Related Services
 
 The `Dto_downloadXml` and `Dto_downloadXsd` delegate to the
-xref:rgsvc.adoc#_rgsvc_api_JaxbService[`JaxbService`] to actually generate the XML/XSD.
\ No newline at end of file
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_JaxbService[`JaxbService`] to actually generate the XML/XSD.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_mixins_Object.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_mixins_Object.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_mixins_Object.adoc
index 21bed1b..ef0b283 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_mixins_Object.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_mixins_Object.adoc
@@ -39,7 +39,7 @@ This mixin actions are all associated with the "Metadata" fieldset.  If there is
 
 === Related Services
 
-This mixin uses the xref:rgsvc.adoc#_rgsvc_spi_HintStore[`HintStore`] service to store and retrieve UI hints for
+This mixin uses the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_HintStore[`HintStore`] service to store and retrieve UI hints for
 each rendered object, per user.
 
 
@@ -61,20 +61,20 @@ public Object downloadLayoutXml(
 <1> either current, complete, normalized or minimal.
 
 See the documentation on xref:ugvw.adoc#_ugvw_layout_file-based[layout XML] and also
-the xref:rgsvc.adoc#_rgsvc_api_LayoutService[`LayoutService`] for more information on these styles
+the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_LayoutService[`LayoutService`] for more information on these styles
 
 
 === Appearance in the UI
 
 This mixin actions are all associated with the "Metadata" fieldset.
 
-A number of other xref:rgcms.adoc#_rgcms_classes_mixins_Persistable[mixins] also contribute properties and actions to the "Metadata" fieldset.
+A number of other xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins_Persistable[mixins] also contribute properties and actions to the "Metadata" fieldset.
 
 
 
 === Related Services
 
-This mixin calls xref:rgsvc.adoc#_rgsvc_api_LayoutService[`LayoutService`] to obtain the layout XML.
+This mixin calls xref:../rgsvc/rgsvc.adoc#_rgsvc_api_LayoutService[`LayoutService`] to obtain the layout XML.
 
 
 
@@ -98,14 +98,14 @@ public void rebuildMetamodel() {
 
 This mixin actions are all associated with the "Metadata" fieldset.
 
-A number of other xref:rgcms.adoc#_rgcms_classes_mixins_Persistable[mixins] also contribute properties and actions to
+A number of other xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins_Persistable[mixins] also contribute properties and actions to
 the "Metadata" fieldset.
 
 
 
 === Related Services
 
-This mixin calls xref:rgsvc.adoc#_rgsvc_api_MetaModelService[`MetaModelService`] and the
-xref:rgsvc.adoc#_rgsvc_spi_GridService[`GridService`] to invalidate their caches.
+This mixin calls xref:../rgsvc/rgsvc.adoc#_rgsvc_api_MetaModelService[`MetaModelService`] and the
+xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_GridService[`GridService`] to invalidate their caches.
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_mixins_Persistable.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_mixins_Persistable.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_mixins_Persistable.adoc
index fb6e930..28e3c89 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_mixins_Persistable.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_mixins_Persistable.adoc
@@ -23,18 +23,18 @@ public Clob downloadJdoMetadata(                    // <1>
     ...
 }
 ----
-<1> returns the XML text wrapped up in a xref:rgcms.adoc#_rgcms_classes_value-types_Clob[`Clob`].
+<1> returns the XML text wrapped up in a xref:../rgcms/rgcms.adoc#_rgcms_classes_value-types_Clob[`Clob`].
 
 
 === Appearance in the UI
 
 This mixin action is associated with the "Metadata" fieldset, and will appear as a panel drop-down action.
 
-These mixin properties are all associated with the "Metadata" fieldset.  The xref:rgcms.adoc#_rgcms_classes_mixins_Object[Object mixin] also contribute an action to the "Metadata" fieldset.
+These mixin properties are all associated with the "Metadata" fieldset.  The xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins_Object[Object mixin] also contribute an action to the "Metadata" fieldset.
 
 === Related Services
 
-The mixin delegates to the xref:rgsvc.adoc#_rgsvc_api_IsisJdoSupport[`IsisJdoSupport`] service to obtain
+The mixin delegates to the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_IsisJdoSupport[`IsisJdoSupport`] service to obtain
 a reference to the JDO `PersistenceManagerFactory`.
 
 
@@ -51,6 +51,6 @@ The framework provides a number of mixins that expose the datanucleus Id and ver
 
 === Appearance in the UI
 
-These mixin properties are all associated with the "Metadata" fieldset.  The xref:rgcms.adoc#_rgcms_classes_mixins_Object[Object mixin] also contribute an action to the "Metadata" fieldset.
+These mixin properties are all associated with the "Metadata" fieldset.  The xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins_Object[Object mixin] also contribute an action to the "Metadata" fieldset.
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_roles_HoldsUpdatedAt.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_roles_HoldsUpdatedAt.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_roles_HoldsUpdatedAt.adoc
index f85dccb..c3a2351 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_roles_HoldsUpdatedAt.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_roles_HoldsUpdatedAt.adoc
@@ -17,9 +17,9 @@ public interface HoldsUpdatedAt {
 }
 ----
 
-The current time is obtained from the xref:rgsvc.adoc#_rgsvc_api_ClockService[`ClockService`].
+The current time is obtained from the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ClockService[`ClockService`].
 
-Entities that implement this interface often also implement xref:rgcms.adoc#_rgcms_classes_roles_HoldsUpdatedBy[`HoldsUpdatedBy`] role interface; as a convenience the xref:rgcms.adoc#_rgcms_classes_roles_Timestampable[`Timestampable`] interface combines the two roles.
+Entities that implement this interface often also implement xref:../rgcms/rgcms.adoc#_rgcms_classes_roles_HoldsUpdatedBy[`HoldsUpdatedBy`] role interface; as a convenience the xref:../rgcms/rgcms.adoc#_rgcms_classes_roles_Timestampable[`Timestampable`] interface combines the two roles.
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_roles_HoldsUpdatedBy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_roles_HoldsUpdatedBy.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_roles_HoldsUpdatedBy.adoc
index d34b295..b7781be 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_roles_HoldsUpdatedBy.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_roles_HoldsUpdatedBy.adoc
@@ -14,6 +14,6 @@ public interface HoldsUpdatedBy {
 }
 ----
 
-Entities that implement this interface often also implement xref:rgcms.adoc#_rgcms_classes_roles_HoldsUpdatedAt[`HoldsUpdatedAt`] role interface; as a convenience the xref:rgcms.adoc#_rgcms_classes_roles_Timestampable[`Timestampable`] interface combines the two roles.
+Entities that implement this interface often also implement xref:../rgcms/rgcms.adoc#_rgcms_classes_roles_HoldsUpdatedAt[`HoldsUpdatedAt`] role interface; as a convenience the xref:../rgcms/rgcms.adoc#_rgcms_classes_roles_Timestampable[`Timestampable`] interface combines the two roles.
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_roles_Timestampable.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_roles_Timestampable.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_roles_Timestampable.adoc
index 3b73e71..154b15d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_roles_Timestampable.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_roles_Timestampable.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-The `Timestampable` role interface is a convenience that combines the xref:rgcms.adoc#_rgcms_classes_roles_HoldsUpdatedAt[`HoldsUpdatedAt`] and xref:rgcms.adoc#_rgcms_classes_roles_HoldsUpdatedBy[`HoldsUpdatedBy`] interfaces.  It is defined as:
+The `Timestampable` role interface is a convenience that combines the xref:../rgcms/rgcms.adoc#_rgcms_classes_roles_HoldsUpdatedAt[`HoldsUpdatedAt`] and xref:../rgcms/rgcms.adoc#_rgcms_classes_roles_HoldsUpdatedBy[`HoldsUpdatedBy`] interfaces.  It is defined as:
 
 [source,java]
 ----
@@ -20,4 +20,4 @@ The interface no additional methods of its own.
 
 == Alternatives
 
-An alternative way to maintain a timestamp is to use JDO's `@Version` annotation.  With this approach, it is the JDO/DataNucleus that maintains the version, rather than the framework's `TimestampService`.  See xref:rgcms.adoc#_rgcms_classes_roles_HoldsUpdatedBy[`HoldsUpdatedBy`] for further details.
+An alternative way to maintain a timestamp is to use JDO's `@Version` annotation.  With this approach, it is the JDO/DataNucleus that maintains the version, rather than the framework's `TimestampService`.  See xref:../rgcms/rgcms.adoc#_rgcms_classes_roles_HoldsUpdatedBy[`HoldsUpdatedBy`] for further details.

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_spec.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_spec.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_spec.adoc
index 73267a3..3dc93b6 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_spec.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_spec.adoc
@@ -7,7 +7,7 @@
 
 The interfaces and classes listed in this chapter provide support for the  `Specification` pattern, as described in Eric Evans' book _Domain Driven Design_, p224.
 
-Apache Isis will automatically apply such specifications as validation rules on properties (as per xref:rgant.adoc#_rgant-Property_mustSatisfy[`@Property#mustSatisfy()`]) and on action parameters (as per xref:rgant.adoc#_rgant-Parameter_mustSatisfy[`@Parameter#mustSatisfy()`]).
+Apache Isis will automatically apply such specifications as validation rules on properties (as per xref:../rgant/rgant.adoc#_rgant-Property_mustSatisfy[`@Property#mustSatisfy()`]) and on action parameters (as per xref:../rgant/rgant.adoc#_rgant-Parameter_mustSatisfy[`@Parameter#mustSatisfy()`]).
 
 
 
@@ -52,7 +52,7 @@ public class Customer {
 [_rgcms_classes_spec-Specification2]
 == `Specification2`
 
-The `Specification2` interface extends the `Specification` API to add support for i18n.  This is done by defining an additional method that returns a xref:rgcms.adoc#_rgcms_classes_i18n_TranslatableString[translatable string]:
+The `Specification2` interface extends the `Specification` API to add support for i18n.  This is done by defining an additional method that returns a xref:../rgcms/rgcms.adoc#_rgcms_classes_i18n_TranslatableString[translatable string]:
 
 [source,java]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_super.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_super.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_super.adoc
index b194d86..c0c7f5e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_super.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_super.adoc
@@ -19,7 +19,7 @@ Impl'n (g: a:)
 |Notes
 
 
-|xref:rgcms.adoc#_rgcms_classes_super_AbstractContainedObject[`o.a.i.applib.` +
+|xref:../rgcms/rgcms.adoc#_rgcms_classes_super_AbstractContainedObject[`o.a.i.applib.` +
 `AbstractContainedObject`]
 |``o.a.i.core`` +
 ``isis-core-applib``
@@ -27,7 +27,7 @@ Impl'n (g: a:)
 |
 
 
-|xref:rgcms.adoc#_rgcms_classes_super_AbstractDomainObject[`o.a.i.applib.` +
+|xref:../rgcms/rgcms.adoc#_rgcms_classes_super_AbstractDomainObject[`o.a.i.applib.` +
 `AbstractDomainObject`]
 |``o.a.i.core`` +
 ``isis-core-applib``
@@ -35,7 +35,7 @@ Impl'n (g: a:)
 |
 
 
-|xref:rgcms.adoc#_rgcms_classes_super_AbstractFactoryAndRepository[`o.a.i.applib.` +
+|xref:../rgcms/rgcms.adoc#_rgcms_classes_super_AbstractFactoryAndRepository[`o.a.i.applib.` +
 `AbstractFactoryAndRepository`]
 |``o.a.i.core`` +
 ``isis-core-applib``
@@ -43,7 +43,7 @@ Impl'n (g: a:)
 |
 
 
-|xref:rgcms.adoc#_rgcms_classes_super_AbstractService[`o.a.i.applib.` +
+|xref:../rgcms/rgcms.adoc#_rgcms_classes_super_AbstractService[`o.a.i.applib.` +
 `AbstractService`]
 |``o.a.i.core`` +
 ``isis-core-applib``
@@ -51,7 +51,7 @@ Impl'n (g: a:)
 |
 
 
-|xref:rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[`o.a.i.applib.` +
+|xref:../rgcms/rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[`o.a.i.applib.` +
 `AbstractSubscriber`]
 |``o.a.i.core`` +
 ``isis-core-applib``
@@ -59,7 +59,7 @@ Impl'n (g: a:)
 |
 
 
-|xref:rgcms.adoc#_rgcms_classes_super_AbstractViewModel[`o.a.i.applib.` +
+|xref:../rgcms/rgcms.adoc#_rgcms_classes_super_AbstractViewModel[`o.a.i.applib.` +
 `AbstractViewModel`]
 |``o.a.i.core`` +
 ``isis-core-applib``
@@ -67,7 +67,7 @@ Impl'n (g: a:)
 |
 
 
-|xref:rgcms.adoc#_rgcms_classes_super_FixtureScript[`o.a.i.applib.` +
+|xref:../rgcms/rgcms.adoc#_rgcms_classes_super_FixtureScript[`o.a.i.applib.` +
 `fixturescript` +
 `FixtureScript`]
 |``o.a.i.core`` +
@@ -76,13 +76,13 @@ Impl'n (g: a:)
 |
 
 
-|xref:rgcms.adoc#_rgcms_classes_super_FixtureScripts[`o.a.i.applib.` +
+|xref:../rgcms/rgcms.adoc#_rgcms_classes_super_FixtureScripts[`o.a.i.applib.` +
 `fixturescripts` +
 `FixtureScripts`]
 |``o.a.i.core`` +
 ``isis-core-applib``
 |(abstract class). +
-`FixtureScriptsDefault` is a default implementation that is used when the alternative xref:rgsvc.adoc#_rgsvc_api_FixtureScriptsSpecificationProvider[`FixtureScriptsSpecificationProvider`] is provided
+`FixtureScriptsDefault` is a default implementation that is used when the alternative xref:../rgsvc/rgsvc.adoc#_rgsvc_api_FixtureScriptsSpecificationProvider[`FixtureScriptsSpecificationProvider`] is provided
   (and no other implementation of `FixtureScripts` was found).
 |depends on: +
 `ClassDiscoveryService`

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_super_AbstractContainedObject.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_super_AbstractContainedObject.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_super_AbstractContainedObject.adoc
index 14adf2c..2b77886 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_super_AbstractContainedObject.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_super_AbstractContainedObject.adoc
@@ -23,10 +23,10 @@ when the transaction is flushed (typically when a query is performed).
 
 * `getContainer()` - which returns the `DomainObjectContainer`
 
-Each of these methods simply delegates to an equivalent method in xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`].
+Each of these methods simply delegates to an equivalent method in xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`].
 
 [TIP]
 ====
-In practice we find that there's little to gain from subclassing; it's easier/less obscure to simply inject xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`] into a simple pojo class.
+In practice we find that there's little to gain from subclassing; it's easier/less obscure to simply inject xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`] into a simple pojo class.
 ====
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_super_AbstractDomainObject.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_super_AbstractDomainObject.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_super_AbstractDomainObject.adoc
index 6edc5ee..298c132 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_super_AbstractDomainObject.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_super_AbstractDomainObject.adoc
@@ -5,10 +5,10 @@
 :_imagesdir: images/
 
 
-This class extends xref:rgcms.adoc#_rgcms_classes_super_AbstractContainedObject[`AbstractContainedObject`], adding
+This class extends xref:../rgcms/rgcms.adoc#_rgcms_classes_super_AbstractContainedObject[`AbstractContainedObject`], adding
 in convenience methods for managing the persistence lifecycle of the object instance.
 
 Each of these methods, eg `isPersistent(...)`, delegates to an equivalent method in
-xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`].
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`].
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_super_AbstractFactoryAndRepository.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_super_AbstractFactoryAndRepository.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_super_AbstractFactoryAndRepository.adoc
index 50d283e..d103cf6 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_super_AbstractFactoryAndRepository.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_super_AbstractFactoryAndRepository.adoc
@@ -5,11 +5,11 @@
 :_imagesdir: images/
 
 
-This class extends xref:rgcms.adoc#_rgcms_classes_super_AbstractContainedObject[`AbstractContainedObject`].  Its
+This class extends xref:../rgcms/rgcms.adoc#_rgcms_classes_super_AbstractContainedObject[`AbstractContainedObject`].  Its
 intent was to be a convenience subclass for services acting as either a repository or a factory, however note that
  all of the methods that it defines are now deprecated.
 
-Instead, indicate that a service is repository using the xref:rgant.adoc#_rgant-DomainService_repositoryFor[`@DomainService#repositoryFor()`] attribute.
+Instead, indicate that a service is repository using the xref:../rgant/rgant.adoc#_rgant-DomainService_repositoryFor[`@DomainService#repositoryFor()`] attribute.
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_super_AbstractService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_super_AbstractService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_super_AbstractService.adoc
index 2174b79..30c1c54 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_super_AbstractService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_super_AbstractService.adoc
@@ -4,7 +4,7 @@
 :_basedir: ../../
 :_imagesdir: images/
 
-This class extends xref:rgcms.adoc#_rgcms_classes_super_AbstractContainedObject[`AbstractContainedObject`], adding
+This class extends xref:../rgcms/rgcms.adoc#_rgcms_classes_super_AbstractContainedObject[`AbstractContainedObject`], adding
 in an implementation of `getId()` based upon the classes name.
 
-In practice there is little to gain from subclassing; simply inject xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`] for broadly equivalent functionality.
+In practice there is little to gain from subclassing; simply inject xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`] for broadly equivalent functionality.

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_super_AbstractSubscriber.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_super_AbstractSubscriber.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_super_AbstractSubscriber.adoc
index f42aeee..2b3f6ea 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_super_AbstractSubscriber.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_super_AbstractSubscriber.adoc
@@ -5,14 +5,14 @@
 :_imagesdir: images/
 
 
-This is a convenience superclass for creating subscriber domain services on the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`].  It uses xref:rgant.adoc#_rgant-PostConstruct[`@PostConstruct`] and
-xref:rgant.adoc#_rgant-PreDestroy[`@PreDestroy`] callbacks to automatically register/unregister itself
+This is a convenience superclass for creating subscriber domain services on the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`].  It uses xref:../rgant/rgant.adoc#_rgant-PostConstruct[`@PostConstruct`] and
+xref:../rgant/rgant.adoc#_rgant-PreDestroy[`@PreDestroy`] callbacks to automatically register/unregister itself
 with the `EventBusService`.
 
 It's important that subscribers register before any domain services that might emit events on the
-xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`].  For example, the (non-ASF) http://github.com/isisaddons/isis-module-security[Isis addons' security] module provides a domain service that automatically
-seeds certain domain entities; these will generate xref:rgcms.adoc#_rgcms_classes_lifecycleevent[lifecycle events] and so
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`].  For example, the (non-ASF) http://github.com/isisaddons/isis-module-security[Isis addons' security] module provides a domain service that automatically
+seeds certain domain entities; these will generate xref:../rgcms/rgcms.adoc#_rgcms_classes_lifecycleevent[lifecycle events] and so
 any subscribers must be registered before such seed services.  The easiest way to do this is to use the
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] attribute.
+xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] attribute.
 
 As a convenience, the `AbstractSubscriber` specifies this attribute.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_super_AbstractViewModel.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_super_AbstractViewModel.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_super_AbstractViewModel.adoc
index a4e32ad..2e2c042 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_super_AbstractViewModel.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_super_AbstractViewModel.adoc
@@ -5,8 +5,8 @@
 :_imagesdir: images/
 
 
-This class extends xref:rgcms.adoc#_rgcms_classes_super_AbstractContainedObject[`AbstractContainedObject`], also
-implementing the xref:rgcms.adoc#_rgcms_classes_super_ViewModel[`ViewModel`] interface.  In and of itself it provides no new behaviour.
+This class extends xref:../rgcms/rgcms.adoc#_rgcms_classes_super_AbstractContainedObject[`AbstractContainedObject`], also
+implementing the xref:../rgcms/rgcms.adoc#_rgcms_classes_super_ViewModel[`ViewModel`] interface.  In and of itself it provides no new behaviour.
 
 [TIP]
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_super_FixtureScripts.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_super_FixtureScripts.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_super_FixtureScripts.adoc
index 2850624..04a8e60 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_super_FixtureScripts.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_super_FixtureScripts.adoc
@@ -4,9 +4,9 @@
 :_basedir: ../../
 :_imagesdir: images/
 
-This abstract class is intended to allow a domain service that can execute xref:rgcms.adoc#_rgcms_classes_super_FixtureScript[`FixtureScript`]s to be easily written.
+This abstract class is intended to allow a domain service that can execute xref:../rgcms/rgcms.adoc#_rgcms_classes_super_FixtureScript[`FixtureScript`]s to be easily written.
 
-However, it has now been deprecated; instead we recommend that the xref:rgsvc.adoc#_rgsvc_spi_FixtureScriptsSpecificationProvider[`FixtureScriptsSpecificationProvider`] service is
-implemented instead.  The framework will then automatically use xref:rgsvc.adoc#_rgsvc_api_FixtureScriptsDefault[`FixtureScriptsDefault`] as a fallback implementation of this class.
+However, it has now been deprecated; instead we recommend that the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_FixtureScriptsSpecificationProvider[`FixtureScriptsSpecificationProvider`] service is
+implemented instead.  The framework will then automatically use xref:../rgsvc/rgsvc.adoc#_rgsvc_api_FixtureScriptsDefault[`FixtureScriptsDefault`] as a fallback implementation of this class.
 
 See the see the xref:ugtst.adoc#_ugtst_fixture-scripts[user guide's testing chapter] for further discussion on the use of fixture scripts, in particular xref:ugtst.adoc#_ugtst_fixture-scripts_api-and-usage[fixture scripts' API and usage].

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_uievent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_uievent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_uievent.adoc
index ce83395..0078668 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_uievent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_uievent.adoc
@@ -7,8 +7,8 @@
 
 This section catalogues the various UI event classes defined by Apache Isis.
 
-These events are broadcast on the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`].  The domain
-events are broadcast as a result of being specified in the xref:rgant.adoc#_rgant-DomainObjectLayout_titleUiEvent[`@DomainObjectLayout#titleUiEvent()`],  xref:rgant.adoc#_rgant-DomainObjectLayout_iconUiEvent[`@DomainObjectLayout#iconUiEvent()`] or xref:rgant.adoc#_rgant-DomainObjectLayout_cssClassUiEvent[`@DomainObjectLayout#cssClassUiEvent()`] attributes.
+These events are broadcast on the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`].  The domain
+events are broadcast as a result of being specified in the xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_titleUiEvent[`@DomainObjectLayout#titleUiEvent()`],  xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_iconUiEvent[`@DomainObjectLayout#iconUiEvent()`] or xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_cssClassUiEvent[`@DomainObjectLayout#cssClassUiEvent()`] attributes.
 
 They are listed in the table below.
 
@@ -23,32 +23,32 @@ Impl'n (g: a:)
 |Notes
 
 
-|xref:rgcms.adoc#_rgcms_classes_uievent_TitleUiEvent[`o.a.i.applib.` +
+|xref:../rgcms/rgcms.adoc#_rgcms_classes_uievent_TitleUiEvent[`o.a.i.applib.` +
 `TitleUiEvent`]
 |``o.a.i.core`` +
 ``services.eventbus`` +
 ``isis-core-applib``
 |(abstract class). +
 `TitleUiEvent.Default` is the concrete implementation used if no `@DomainObjectLayout#titleUiEvent` attribute is specified
-|Broadcast whenever there is a requirement to obtain a title for a domain object.  Note that if the domain object defines its own xref:rgcms.adoc#_rgcms_methods_reserved_title[`title()`] supporting method, or has xref:rgant.adoc#_rgant-Title[`@Title`] annotation(s) on its properties, then these will take precedence.
+|Broadcast whenever there is a requirement to obtain a title for a domain object.  Note that if the domain object defines its own xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_title[`title()`] supporting method, or has xref:../rgant/rgant.adoc#_rgant-Title[`@Title`] annotation(s) on its properties, then these will take precedence.
 
-|xref:rgcms.adoc#_rgcms_classes_uievent_IconUiEvent[`o.a.i.applib.` +
+|xref:../rgcms/rgcms.adoc#_rgcms_classes_uievent_IconUiEvent[`o.a.i.applib.` +
 `IconUiEvent`]
 |``o.a.i.core`` +
 ``services.eventbus`` +
 ``isis-core-applib``
 |(abstract class). +
 `IconUiEvent.Default` is the concrete implementation used if no `@DomainObjectLayout#iconUiEvent` attribute is specified
-|Broadcast whenever there is a requirement to obtain an icon (or rather, the name of an icon) for a domain object.  Note that if the domain object defines its own xref:rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`] supporting method, or if it has the xref:rgant.adoc#_rgant-DomainObjectLayout#cssClassFa[`@DomainObjectLayout#cssClassFa()`] attribute, then these will take precedence.
+|Broadcast whenever there is a requirement to obtain an icon (or rather, the name of an icon) for a domain object.  Note that if the domain object defines its own xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`] supporting method, or if it has the xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout#cssClassFa[`@DomainObjectLayout#cssClassFa()`] attribute, then these will take precedence.
 
-|xref:rgcms.adoc#_rgcms_classes_uievent_CssClassUiEvent[`o.a.i.applib.` +
+|xref:../rgcms/rgcms.adoc#_rgcms_classes_uievent_CssClassUiEvent[`o.a.i.applib.` +
 `CssClassUiEvent`]
 |``o.a.i.core`` +
 ``services.eventbus`` +
 ``isis-core-applib``
 |(abstract class). +
 `CssClassUiEvent.Default` is the concrete implementation used if no `@DomainObjectLayout#cssClassUiEvent` attribute is specified
-|Broadcast whenever there is a requirement to obtain a CSS class hint for a domain object.  Note that if the domain object defines its own xref:rgcms.adoc#_rgcms_methods_reserved_cssClass[`cssClass()`] supporting method then this
+|Broadcast whenever there is a requirement to obtain a CSS class hint for a domain object.  Note that if the domain object defines its own xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_cssClass[`cssClass()`] supporting method then this
 will take precedence.
 
 |===

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_uievent_CssClassUiEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_uievent_CssClassUiEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_uievent_CssClassUiEvent.adoc
index e1776e7..2403491 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_uievent_CssClassUiEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_uievent_CssClassUiEvent.adoc
@@ -17,6 +17,6 @@ The class itself is instantiated automatically by the framework whenever interac
 
 [NOTE]
 ====
-if the domain object defines its own xref:rgcms.adoc#_rgcms_methods_reserved_cssClass[`cssClass()`] supporting
+if the domain object defines its own xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_cssClass[`cssClass()`] supporting
 method then this will take precedence.
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_uievent_IconUiEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_uievent_IconUiEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_uievent_IconUiEvent.adoc
index 5e47a36..7adfcd0 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_uievent_IconUiEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_uievent_IconUiEvent.adoc
@@ -16,8 +16,8 @@ The class itself is instantiated automatically by the framework whenever interac
 
 [NOTE]
 ====
-If the domain object defines its own xref:rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`] supporting method,
+If the domain object defines its own xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`] supporting method,
 or if it has the
-xref:rgant.adoc#_rgant-DomainObjectLayout#cssClassFa[`@DomainObjectLayout#cssClassFa()`] attribute, then
+xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout#cssClassFa[`@DomainObjectLayout#cssClassFa()`] attribute, then
 these will take precedence.
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_uievent_TitleUiEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_uievent_TitleUiEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_uievent_TitleUiEvent.adoc
index 9218b6f..84415d4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_uievent_TitleUiEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_uievent_TitleUiEvent.adoc
@@ -16,7 +16,7 @@ The class itself is instantiated automatically by the framework whenever interac
 
 [NOTE]
 ====
-If the domain object defines its own xref:rgcms.adoc#_rgcms_methods_reserved_title[`title()`] supporting method, or
-has xref:rgant.adoc#_rgant-Title[`@Title`] annotation(s) on its properties, then these will take
+If the domain object defines its own xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_title[`title()`] supporting method, or
+has xref:../rgant/rgant.adoc#_rgant-Title[`@Title`] annotation(s) on its properties, then these will take
 precedence.
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_utility_TitleBuffer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_utility_TitleBuffer.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_utility_TitleBuffer.adoc
index 0030b18..fab11ff 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_utility_TitleBuffer.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_utility_TitleBuffer.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-The `TitleBuffer` utility class is intended to make it easy to construct title strings (returned from the xref:rgcms.adoc#_rgcms_methods_reserved_title[`title()`] method).
+The `TitleBuffer` utility class is intended to make it easy to construct title strings (returned from the xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_title[`title()`] method).
 
 For example, it has overloaded versions of methods called `append()` and `concat()`.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_value-types_Blob.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_value-types_Blob.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_value-types_Blob.adoc
index 3850c5b..14c7143 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_value-types_Blob.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_value-types_Blob.adoc
@@ -46,5 +46,5 @@ private Blob someImage;
 
 [TIP]
 ====
-For character large objects, use xref:rgcms.adoc#_rgcms_classes_value-types_Clob][`Clob`] value type.
+For character large objects, use xref:../rgcms/rgcms.adoc#_rgcms_classes_value-types_Clob][`Clob`] value type.
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_value-types_Clob.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_value-types_Clob.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_value-types_Clob.adoc
index 3c51930..99ad6d3 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_value-types_Clob.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_value-types_Clob.adoc
@@ -50,7 +50,7 @@ private Clob someClob;
 
 [TIP]
 ====
-For binary large objects, use xref:rgcms.adoc#_rgcms_classes_value-types_Blob][`Blob`] value type.
+For binary large objects, use xref:../rgcms/rgcms.adoc#_rgcms_classes_value-types_Blob][`Blob`] value type.
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods.adoc
index 913032e..f6c6cf0 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods.adoc
@@ -6,7 +6,7 @@
 
 
 
-The Apache Isis metamodel is built up from declaratively (ie, xref:rgant.adoc#_rgant[annotations]) and imperatively, from "supporting" methods and other reserved methods.
+The Apache Isis metamodel is built up from declaratively (ie, xref:../rgant/rgant.adoc#_rgant[annotations]) and imperatively, from "supporting" methods and other reserved methods.
 
 This chapter documents the supporting methods and the reserved methods.  It also documents (separately) the reserved methods that act as callback hooks into the persistence lifecycle of domain entities.
 

[45/58] [abbrv] isis git commit: ISIS-1521: further minor updates to ugfun.adoc

[da...@apache.org]

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_class-definition.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_class-definition.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_class-definition.adoc
deleted file mode 100644
index 70b3659..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_class-definition.adoc
+++ /dev/null
@@ -1,201 +0,0 @@
-[[_ugfun_how-tos_class-structure_class-definition]]
-= Class Definition
-: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 supports recognises three main types of domain classes:
-
-* domain entities - domain objects persisted to the database using JDO/DataNucleus; for example `Customer`
-
-* domain services - generally singletons, automatically injected, and providing various functionality; for example `CustomerRepository`
-
-* view models - domain objects that are a projection of some state held by the database, in support a particular use case; for example `CustomerDashboard` (to pull together commonly accessed information about a customer).
-
-Domain classes are generally recognized using annotations.
-Apache Isis defines its own set of annotations, while entities are annotated using JDO/DataNucleus (though XML can also be used if required).
-JAXB can also be used for view models.
-Apache Isis recognizes some of the JDO and JAXB annotations and infers domain semantics from these annotations.
-
-You can generally recognize an Apache Isis domain class because it will be probably be annotated using `@DomainObject` and `@DomainService`.
-The framework also defines supplementary annotations, `@DomainObjectLayout` and `@DomainServiceLayout`.
-These provide hints relating to the layout of the domain object in the user interface.
-(Alternatively, these UI hints can be defined in a supplementary xref:../ugvw/ugvw.adoc#_ugvw_layout[`.layout.xml`] file.
-
-We use Maven modules as a way to group related domain objects together; we can then reason about all the classes in that module as a single unit.
-By convention there will be a single top-level package corresponding to the module.
-
-For example, the (non-ASF) link:https://github.com/incodehq/incode-module-document[Document module] (part of the link:http://catalog.incode.org[Incode Catalog]) has a top-level package of `org.incode.module.document`.
-Within the module there may be various subpackages, but its the module defines the namespace.
-
-In the same way that the Java module act as a namespace for domain objects, it's good practice to map domain entities to their own (database) schemas.
-
-
-[[__ugfun_how-tos_class-structure_class-definition_entities]]
-== Entities
-
-Entities are persistent domain objects.
-Their persistence is handled by JDO/DataNucleus, which means that it will generally be decorated with both DataNucleus and Apache Isis annotations.
-The following is typical:
-
-[source,java]
-----
-@javax.jdo.annotations.PersistenceCapable(                                      // <1>
-        identityType=IdentityType.DATASTORE,                                    // <2>
-        schema = "simple",                                                      // <3>
-        table = "SimpleObject"
-)
-@javax.jdo.annotations.DatastoreIdentity(                                       // <4>
-        strategy=javax.jdo.annotations.IdGeneratorStrategy.IDENTITY,
-        column="id"
-)
-@javax.jdo.annotations.Version(                                                 // <5>
-        strategy= VersionStrategy.DATE_TIME,
-        column="version"
-)
-@javax.jdo.annotations.Queries({
-        @javax.jdo.annotations.Query(                                           // <6>
-                name = "findByName",
-                value = "SELECT "
-                        + "FROM domainapp.modules.simple.dom.impl.SimpleObject "
-                        + "WHERE name.indexOf(:name) >= 0 ")
-})
-@javax.jdo.annotations.Unique(name="SimpleObject_name_UNQ", members = {"name"}) // <7>
-@DomainObject(                                                                  // <8>
-        objectType = "simple.SimpleObject"
-)
-public class SimpleObject
-             implements Comparable<SimpleObject> {                              // <9>
-
-    public SimpleObject(final String name) {                                    // <10>
-        setName(name);
-    }
-
-    ...
-
-    @Override
-    public String toString() {
-        return ObjectContracts.toString(this, "name");                          // <11>
-    }
-    @Override
-    public int compareTo(final SimpleObject other) {
-        return ObjectContracts.compare(this, other, "name");                    // <9>
-    }
-}
-----
-<1> The `@PersistenceCapable` annotation indicates that this is an entity to DataNucleus.
-The DataNucleus enhancer acts on the bytecode of compiled entities, injecting lazy loading and dirty object tracking functionality.
-Enhanced entities end up also implementing the `javax.jdo.spi.PersistenceCapable` interface.
-<2> Indicates how identifiers for the entity are handled.
-Using `DATASTORE` means that a DataNucleus is responsible for assigning the value (rather than the application).
-<3> Specifies the RDBMS database schema and table name for this entity will reside.
-The schema should correspond with the module in which the entity resides.
-The table will default to the entity name if omitted.
-<4> For entities that are using `DATASTORE` identity, indicates how the id will be assigned.
-A common strategy is to allow the database to assign the id, for example using an identity column or a sequence.
-<5> The `@Version` annotation is useful for optimistic locking; the strategy indicates what to store in the `version` column.
-<6> The `@Query` annotation (usually several of them, nested within a `@Queries` annotation) defines queries using JDOQL.
-DataNucleus provides several APIs for defining queries, including entirely programmatic and type-safe APIs; but JDOQL is very similar to SQL and so easily learnt.
-<7> DataNucleus will automatically add a unique index to the primary surrogate id (discussed above), but additional alternative keys can be defined using the `@Unique` annotation.
-In the example above, the "name" property is assumed to be unique.
-<8> The `@DomainObject` annotation identifies the domain object to Apache Isis (not DataNucleus).
-It isn't necessary to include this annotation -- at least, not for entities -- but it is nevertheless recommended.
-In particular, its strongly recommended that the `objectType` (which acts like an alias to the concrete domain class) is specified; note that it corresponds to the schema/table for DataNucleus' `@PersistenceCapable` annotation.
-<9> Although not required, we strongly recommend that all entities are naturally `Comparable`.
-This then allows parent/child relationships to be defined using ``SortedSet``s; RDBMS after all are set-oriented.
-The `ObjectContracts` utility class provided by Apache Isis makes it easy to implement the `compareTo()` method, but you can also just use an IDE to generate an implementation or roll your own.
-<10> Chances are that some of the properties of the entity will be mandatory, for example any properties that represent an alternate unique key to the entity.
-In regular Java programming we would represent this using a constructor that defines these mandatory properties, and in Apache Isis/DataNucleus we can likewise define such a constructor.
-When DataNucleus rehydrates domain entities from the database at runtime, it actually requires a no-arg constructor (it then sets all state reflectively).
-However, there is no need to provide such a no-arg constructor; it is added by the enhancer process.
-<11> The `ObjectContracts` utility class also provides assistance for `toString()`, useful when debugging in an IDE.
-
-
-[[__ugfun_how-tos_class-structure_class-definition_domain-services]]
-== Domain Services
-
-Domain services are generally singletons that are automatically injected into other domain services.
-A very common usage is as a repository (to find/locate existing entities) or as a factory (to create new instances of entities).
-But services can also be exposed in the UI as top-level menus; and services are also used as a bridge to access technical resources (eg rendering a document object as a PDF).
-
-The Apache Isis framework itself also provides a large number of number of domain services, catalogued in the xref:../rgsvc/rgsvc.adoc#[Domain Services Reference Guide].
-Some of these are APIs (intended to be called by your application's own domain objects) and some are SPIs (implemented by your application and called by the framework, customising the way it works).
-
-The following is a typical menu service:
-
-[source,java]
-----
-@DomainService(                                                 // <1>
-        nature = NatureOfService.VIEW_MENU_ONLY
-)
-@DomainServiceLayout(                                           // <2>
-        named = "Simple Objects",
-        menuOrder = "10"
-)
-public class SimpleObjectMenu {
-
-    ...
-
-    @Action(semantics = SemanticsOf.SAFE)
-    @ActionLayout(bookmarking = BookmarkPolicy.AS_ROOT)
-    @MemberOrder(sequence = "2")
-    public List<SimpleObject> findByName(                       // <3>
-            @ParameterLayout(named="Name")
-            final String name
-    ) {
-        return simpleObjectRepository.findByName(name);
-    }
-
-    @javax.inject.Inject
-    SimpleObjectRepository simpleObjectRepository;              // <4>
-}
-----
-<1> The (Apache Isis) `@DomainService` annotation is used to identify the class as a domain service.
-Apache Isis scans the classpath looking for classes with this annotation, so there very little configuration other than to tell the framework which packages to scan underneath.
-The `VIEW_MENU_ONLY` nature indicates that this service's actions should be exposed as menu items.
-<2> The (Apache Isis) `@DomainServiceLayout` annotation provides UI hints.
-In the example above the menu is named "Simple Objects" (otherwise it would have defaulted to "Simple Object Menu", based on the class name, while the `menuOrder` attribute determines the order of the menu with respect to other menu services.
-<3> The `findByName` method is annotated with various Apache Isis annotations (`@Action`, `@ActionLayout` and `@MemberOrder`) and is itself rendered in the UI as a "Find By Name" menu item underneath the "Simple Objects" menu.
-The implementation delegates to an `SimpleObjectRepository` service, which is injected.
-<4> The `javax.inject.Inject` annotation instructs Apache Isis framework to inject the `SimpleObjectRepository` service into this domain object.
-The framework can inject into not just other domain services but will also automatically into domain entities and view models.
-There is further discussion of service injection xref:../ugfun/ugfun.adoc#_ugfun_how-tos_class-structure_inject-services[below].
-
-
-[[__ugfun_how-tos_class-structure_class-definition_view-models]]
-== View Models
-
-xref:../ugbtb/ugbtb.adoc#_ugbtb_view-models[View model]s are similar to entities in that (unlike domain services) there can be many instances of any given type; but they differ from entities in that they are not persisted into a database.
-Instead they are recreated dynamically by serializing their state, ultimately into the URL itself.
-
-A common use case for view models is to support a business process.
-For example, in an invoicing application there could be an `InvoiceRun` view model, which lists all the invoices due to be paid (each month, say) and provides actions to allow those invoices to be processed.
-
-Another use case is for a view model to act as a proxy for an entity that is managed in an external system.
-For example, a `Content` view model could represent a PDF that has been scanned and is held within a separate Content Management system.
-
-A third use case is to define DTOs that act as a stable projection of one or more underlying entities.
-Apache Isis' xref:../ugvro/ugvro.adoc[Restful Objects] viewer provides a REST API that then allows REST clients to query the application using these DTOs; useful for integration scenarios.
-
-Apache Isis offers several ways to implement view models, but the most flexible/powerful is to annotate the class using JAXB annotations.
-For example:
-
-[source,java]
-----
-@XmlRootElement(name = "invoiceRun")    // <1>
-@XmlType(
-        propOrder = {                   // <2>
-            ...
-        }
-)
-public class InvoiceRun {
-    ...
-}
-----
-<1> The JAXB `@XmlRootElement` annotation indicates this is a view model to Apache Isis, which then uses JAXB to serialize the state of the view model between interactions
-<2> All properties of the view model must be listed using the `XmlType#propOrder` attribute.
-
-Use JAXB elements such as `@XmlElement` for properties and the combination of `@XmlElementWrapper` and `@XmlElement` for collections.
-Properties can be ignored (for serialization) using `@XmlTransient`.

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_collections.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_collections.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_collections.adoc
deleted file mode 100644
index 16a58de..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_collections.adoc
+++ /dev/null
@@ -1,99 +0,0 @@
-[[_ugfun_how-tos_class-structure_collections]]
-= Collections
-: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/
-
-
-A collection is an instance variable of a domain object, of a collection type that holds references to other domain objects.
-For example, a `Customer` may have a collection of ``Order``s).
-
-It's ok for a xref:../ugfun/ugfun.adoc#__ugfun_how-tos_class-structure_class-definition_entities[domain entity] to reference another domain entity, and for a xref:../ugfun/ugfun.adoc#__ugfun_how-tos_class-structure_class-definition_view-models[view model] to reference both view model and domain entities.
-However, it isn't valid for a domain entity to hold a persisted reference to view model (DataNucleus will not know how to persist that view model).
-
-Formally speaking, a collection is simply a regular JavaBean getter, returning a collection type (subtype of `java.util.Collection`).
-Most collections (those that are modifiable) will also have a setter and (if persisted) a backing instance field.
-And collections properties will also have a number of annotations:
-
-* Apache Isis defines its own set own `@Collection` annotation for capturing domain semantics.
-It also provides a `@CollectionLayout` for UI hints (though the information in this annotation may instead be provided by a supplementary xref:../ugvw/ugvw.adoc#_ugvw_layout[`.layout.xml`] file
-
-* the collections of domain entities are often annotated with various JDO/DataNucleus annotations, most notable `javax.jdo.annotations.Persistent`.
-This and other annotations can be used to specify if the association is bidirectional, and whether to define a link table or not to hold foreign key columns.
-
-* for the collections of view models, then JAXB annotations such as `@javax.xml.bind.annotation.XmlElementWrapper` and `@javax.xml.bind.annotation.XmlElement` will be present
-
-Apache Isis recognises some of these annotations for JDO/DataNucleus and JAXB and infers some domain semantics from them (for example, the maximum allowable length of a string property).
-
-Unlike xref:../ugfun/ugfun.adoc#_ugfun_how-tos_class-structure_properties[properties], the framework (at least, the xref:../ugvw/ugvw.adoc[Wicket viewer]) does not allow collections to be "edited".
-Instead, xref:../ugfun/ugfun.adoc#_ugfun_how-tos_class-structure_actions[action]s can be written that will modify the contents of the collection as a side-effect.
-For example, a `placeOrder(...)` action will likely add an `Order` to the `Customer#orders` collection.
-
-Since writing getter and setter methods adds quite a bit of boilerplate, it's common to use link:https://projectlombok.org/[Project Lombok] to code generate these methods at compile time (using Java's annotation processor) simply by adding the `@lombok.Getter` and `@lombok.Setter` annotations to the field.
-
-
-== Mapping bidir 1:m
-
-Bidirectional one-to-many collections are one of the most common types of associations between two entities.
-In the parent object, the collection can be defined as:
-
-[source,java]
-----
-public class ParentObject
-        implements Comparable<ParentObject>{
-
-    @javax.jdo.annotations.Persistent(
-        mappedBy = "parent",                                                // <1>
-        dependentElement = "false"                                          // <2>
-    )
-    @Collection                                                             // <3>
-    @lombok.Getter @lombok.Setter
-    private SortedSet<ChildObject> children = new TreeSet<ChildObject>();   // <4>
-
-}
-----
-<1> indicates a bidirectional association; the foreign key pointing back to the `Parent` will be in the table for `ChildObject`
-<2> disable cascade delete
-<3> (not actually required in this case, because no attributes are set, but acts as a useful reminder that this collection will be rendered in the UI by Apache Isis)
-<4> uses a `SortedSet` (as opposed to some other collection type; discussion below)
-
-while in the child object you will have:
-
-[source,java]
-----
-public class ChildObject
-        implements Comparable<ChildObject> {    // <1>
-
-    @javax.jdo.annotations.Column(
-        allowsNull = "false"                    // <2>
-    )
-    @Property(editing = Editing.DISABLED)       // <3>
-    @lombok.Getter @lombok.Setter
-    private ParentObject parent;
-}
-----
-<1> implements `Comparable` because is mapped using a `SortedSet`
-<2> mandatory; every child must reference its parent
-<3> cannot be edited directly
-
-Generally speaking you should use `SortedSet` for collection types (as opposed to `Set`, `List` or `Collection`).
-JDO/Datanucleus does support the mapping of these other types, but RDBMS are set-oriented, so using this type introduces the least friction.
-
-[NOTE]
-====
-For further details on mapping associations, see the JDO/DataNucleus documentation for link:http://www.datanucleus.org/products/accessplatform_4_1/jdo/orm/one_to_many.html[one-to-many] associations, link:http://www.datanucleus.org/products/accessplatform_4_1/jdo/orm/many_to_one.html[many-to-one] associations, link:http://www.datanucleus.org/products/accessplatform_4_1/jdo/orm/many_to_many.html[many-to-many] associations, and so on.
-
-Also, while JDO/DataNucleus itself supports `java.util.Map` as a collection type, this is not supported by Apache Isis.
-If you do wish to use this collection type, then annotate the getter with `@Programmatic` so that it is ignored by the Apache Isis framework.
-====
-
-
-
-== Value vs Reference Types
-
-Apache Isis can (currently) only provide a UI for collections of references.
-While you can use DataNucleus to persist collections/arrays of value types, such properties must be annotated as `@Programmatic` so that they are ignored by Apache Isis.
-
-If you want to visualize an array of value types in Apache Isis, then one option is to wrap value in a view model, as explained xref:../ugfun/ugfun.adoc#_ugfun_how-tos_simulating-collections-of-values[elsewhere].
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_inject-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_inject-services.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_inject-services.adoc
deleted file mode 100644
index 26c5682..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_inject-services.adoc
+++ /dev/null
@@ -1,103 +0,0 @@
-[[_ugfun_how-tos_class-structure_inject-services]]
-= Injecting services
-: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 autowires (automatically injects) domain services into each entity, as well as into the domain services themselves, using either method injection or field injection.
-The framework defines many additional services (such as xref:../rgsvc/rgsvc.adoc#_rgsvc_api_RepositoryService[`RepositoryService`]); these are injected in exactly the same manner.
-
-Sometimes there may be multiple services that implement a single type.
-This is common for example for SPI service, whereby one module defines an SPI service, and other module(s) in the application implement that service.
-To support this, the framework also allows lists of services to be injected.
-
-When there are multiple service implementations of a given type, the framework will inject the service with highest priority, as defined through xref:../rgant/rgant.adoc#_rgant_DomainService_menuOrder[`@DomainService#menuOrder()`] (even for domain services that are not menus), lowest first.
-If a list of services is injected, then that list will be ordered according to `menuOrder`, again lowest first.
-
-
-
-[NOTE]
-====
-Isis currently does _not_ support qualified injection of services; the domain service of each type must be distinct from any other.
-
-If you find a requirement to inject two instances of type `SomeService`, say, then the work-around is to create trivial subclasses `SomeServiceA` and `SomeServiceB` and inject these instead.
-====
-
-
-== Field Injection
-
-Field injection is recommended, using the `@javax.inject.Inject` annotation.
-For example:
-
-[source,java]
-----
-public class Customer {
-    ...
-    @javax.inject.Inject
-    OrderRepository orderRepository;
-}
-----
-
-To inject a list of services, use:
-
-[source,java]
-----
-public class DocumentService {
-    ...
-    @javax.inject.Inject
-    List<PaperclipFactory> paperclipFactories;
-}
-----
-
-We recommend using default rather than `private` visibility so that the field can be mocked out within unit tests (placed in the same package as the code under test).
-
-
-
-
-== Method Injection
-
-The framework also supports two forms of method injection.
-All that is required to inject a service into a entity/service is to provide an appropriate method or field.
-The name of the method does not matter, only that it is prefixed either `set` or `inject`, is public, and has a single parameter of the correct type.
-
-For example:
-
-[source,java]
-----
-public class Customer {
-    private OrderRepository orderRepository;
-    public void setOrderRepository(OrderRepository orderRepository) {
-        this.orderRepository = orderRepository;
-    }
-    ...
-}
-----
-
-or alternatively, using 'inject' as the prefix:
-
-[source,java]
-----
-public class Customer {
-    private OrderRepository orderRepository;
-    public void injectOrderRepository(OrderRepository orderRepository) {
-        this.orderRepository = orderRepository;
-    }
-    ...
-}
-----
-
-Lists of services can be injected in a similar manner.
-
-Note that the method name can be anything; it doesn't need to be related to the type being injected.
-
-
-== Constructor injection
-
-Simply to note that constructor injection is _not_ supported by Apache Isis (and is unlikely to be, because the JDO specification for entities requires a no-arg constructor).
-
-
-
-
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_properties-vs-parameters.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_properties-vs-parameters.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_properties-vs-parameters.adoc
deleted file mode 100644
index c435cb3..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_properties-vs-parameters.adoc
+++ /dev/null
@@ -1,38 +0,0 @@
-[[_ugfun_how-tos_class-structure_properties-vs-parameters]]
-= Properties vs Parameters
-: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/
-
-
-In many cases the value types of properties and of action parameters align.
-For example, a `Customer` entity might have a `surname` property, and there might also be corresponding `changeSurname`.
-Ideally we want the surname property and surname action parameter to use the same value type.
-
-Since JDO/DataNucleus handles persistence, its annotations are requiredto specify semantics such as optionality or maximum length on properties.
-However, they cannot be applied to action parameters.
-It is therefore necessary to use Apache Isis' equivalent annotations for action parameters.
-
-The table below summarises the equivalence of some of the most common cases.
-
-.Comparing annotations of Properties vs Action Parameters
-[cols="2,3,3", options="header"]
-|===
-|value type/semantic
-|(JDO) property
-|action parameter
-
-|string (length)
-|`@javax.jdo.annotations.Column(length=50)`
-|`@javax.jdo.annotations.Parameter(maxLength=50)`
-
-|big decimal (precision)
-|`@javax.jdo.annotations.Column(scale=2)`
-|`@javax.validation.constraints.Digits(fraction=2)`
-
-|optionality
-|`@Column(allowsNull="true")`
-|`@Nullable` or `ParameterLayout(optionality=Optionality.OPTIONAL`) (also `@Optional`, now deprecated)
-|===
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_properties.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_properties.adoc
deleted file mode 100644
index 5a49a5b..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_properties.adoc
+++ /dev/null
@@ -1,397 +0,0 @@
-[[_ugfun_how-tos_class-structure_properties]]
-= Property
-: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/
-
-
-A property is an instance variable of a domain object, of a scalar type, that holds some state about either a xref:../ugfun/ugfun.adoc#__ugfun_how-tos_class-structure_class-definition_entities[domain entity] or a xref:../ugfun/ugfun.adoc#__ugfun_how-tos_class-structure_class-definition_view-models[view model].
-
-For example, a ``Customer``'s `firstName` would be a property, as would their `accountCreationDate` that they created their account.
-All properties have at least a "getter" method, and most properties have also a "setter" method (meaning that they are mutable).
-Properties that do _not_ have a setter method are derived properties, and so are not persisted.
-
-Formally speaking, a property is simply a regular JavaBean getter, returning a scalar value recognized by the framework.
-Most properties (those that are editable/modifiable) will also have a setter and (if persisted) a backing instance field.
-And most properties will also have a number of annotations:
-
-* Apache Isis defines its own set own `@Property` annotation for capturing domain semantics.
-It also provides a `@PropertyLayout` for UI hints (though the information in this annotation may instead be provided by a supplementary xref:../ugvw/ugvw.adoc#_ugvw_layout[`.layout.xml`] file
-
-* the properties of domain entities are often annotated with the JDO/DataNucleus `@javax.jdo.annotations.Column` annotation.
-For property references, there may be other annotations to indicate whether the reference is bidirectional.
-It's also possible (using annotations) to define a link table to hold foreign key columns.
-
-* for the properties of view models, then JAXB annotations such as `@javax.xml.bind.annotation.XmlElement` will be present
-
-Apache Isis recognises some of these annotations for JDO/DataNucleus and JAXB and infers some domain semantics from them (for example, the maximum allowable length of a string property).
-
-Since writing getter and setter methods adds quite a bit of boilerplate, it's common to use link:https://projectlombok.org/[Project Lombok] to code generate these methods at compile time (using Java's annotation processor) simply by adding the `@lombok.Getter` and `@lombok.Setter` annotations to the field.
-The xref:guides/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] uses this approach.
-
-
-[[__ugfun_how-tos_class-structure_properties_value-vs-reference-types]]
-== Value vs Reference Types
-
-Properties can be either a value type (strings, int, date and so on) or be a reference to another object (for example, an `Order` referencing the `Customer` that placed it).
-
-For example, to map a string value type:
-
-[source,java]
-----
-@lombok.Getter @lombok.Setter       // <1>
-private String notes;
-----
-<1> using link:https://projectlombok.org/[Project Lombok] annotations to reduce boilerplate
-
-You could also add the `@Property` annotation if you wished:
-
-[source,java]
-----
-@Property
-@lombok.Getter @lombok.Setter
-private String notes;
-----
-
-Although in this case it is not required (none of its attributes have been set).
-
-Or to map a reference type:
-
-[source,java]
-----
-@lombok.Getter @lombok.Setter
-private Customer customer;
-----
-
-It's ok for a xref:../ugfun/ugfun.adoc#__ugfun_how-tos_class-structure_class-definition_entities[domain entity] to reference another domain entity, and for a xref:../ugfun/ugfun.adoc#__ugfun_how-tos_class-structure_class-definition_view-models[view model] to reference both view model and domain entities.
-However, it isn't valid for a domain entity to hold a persisted reference to view model (DataNucleus will not know how to persist that view model).
-
-[NOTE]
-====
-For further details on mapping associations, see the JDO/DataNucleus documentation for link:http://www.datanucleus.org/products/accessplatform_4_1/jdo/orm/one_to_many.html[one-to-many] associations, link:http://www.datanucleus.org/products/accessplatform_4_1/jdo/orm/many_to_one.html[many-to-one] associations, link:http://www.datanucleus.org/products/accessplatform_4_1/jdo/orm/many_to_many.html[many-to-many] associations, and so on.
-====
-
-For domain entities, the annotations for mapping value types tend to be different for properties vs action parameters, because JDO annotations are only valid on properties.
-The table in the xref:../ugfun/ugfun.adoc#_ugfun_how-tos_class-structure_properties-vs-parameters[Properties vs Parameters] section provides a handy reference of each.
-
-
-[[__ugfun_how-tos_class-structure_properties_optional-properties]]
-== Optional Properties
-
-(For domain entities) JDO/DataNucleus' default is that a property is assumed to be mandatory if it is a primitive type (eg `int`, `boolean`), but optional if a reference type (eg `String`, `BigDecimal` etc).
-To override optionality in JDO/DataNucleus the `@Column(allowsNull="...")` annotations is used.
-
-Apache Isis on the other hand assumes that all properties (and action parameters, for that matter) are mandatory, not optional.
-These defaults can also be overridden using Apache Isis' own annotations, specifically `@Property(optionality=...)`, or (because it's much less verbose) using `@javax.annotation.Nullable`.
-
-These different defaults can lead to incompatibilities between the two frameworks.
-To counteract that, Apache Isis also recognizes and honours JDO's `@Column(allowsNull=...)`.
-
-For example, you can write:
-
-[source,java]
-----
-@javax.jdo.annotations.Column(allowsNull="true")
-@lombok.Getter @lombok.Setter
-private LocalDate date;
-----
-
-rather than the more verbose:
-
-[source,java]
-----
-@javax.jdo.annotations.Column(allowsNull="true")
-@Property(optionality=Optionality.OPTIONAL)
-@lombok.Getter @lombok.Setter
-private LocalDate date;
-----
-
-The framework will search for any incompatibilities in optionality (whether specified explicitly or defaulted implicitly) between Isis' defaults and DataNucleus, and refuse to boot if any are found (fail fast).
-
-[[__ugfun_how-tos_class-structure_properties_editable-properties]]
-== Editable Properties
-
-Apache Isis provides the capability to allow individual properties to be modified.
-This is specified using the `@Property(editing=...)` attribute.
-
-For example:
-
-[source,java]
-----
-@Property(editing = Editing.ENABLED)
-@lombok.Getter @lombok.Setter
-private String notes;
-----
-
-If this is omitted then whether editing is enabled or disabled is defined globally, in the `isis.properties` configuration file; see xref:../rgcfg/rgcfg.adoc#__rgcfg_configuring-core_isis-objects-editing[reference configuration guide] for further details.
-
-
-[[__ugfun_how-tos_class-structure_properties_ignoring-properties]]
-== Ignoring Properties
-
-By default Apache Isis will automatically render all properties in the xref:../ugvw/ugvw.adoc[UI] or in the xref:../ugvro/ugvro.adoc[REST API].
-To get Apache Isis to ignore a property (exclude it from its metamodel), annotate the getter using `@Programmatic`.
-
-Similarly, you can tell JDO/DataNucleus to ignore a property using the `@javax.jdo.annotations.NotPersistent` annotation.
-This is independent of Apache Isis; in other words that property will still be rendered in the UI (unless also annotated with `@Programmatic`).
-
-For view models, you can tell JAXB to ignore a property using the `@javax.xml.bind.annotation.XmlTransient` annotation.
-Again, this is independent of Apache Isis.
-
-
-[[__ugfun_how-tos_class-structure_properties_derived-properties]]
-== Derived Properties
-
-Derived properties are those with a getter but no setter.
-Provided that the property has not been annotated with `@Programmatic`, these will still be rendered in the UI, but they will be read-only (not editable) and their state will not be persisted.
-
-Subtly different, it is also possible to have non-persisted but still editable properties.
-In this case you will need a getter and a setter, but with the getter annotated using `@NotPersistent`.
-The implementation of these getters and setters will most likely persist state using other properties (which might be hidden from view using `@Programmatic`).
-
-For example:
-
-[source,java]
-----
-@javax.jdo.annotations.NotPersistent
-@Property(editing=Editing.ENABLED)
-public String getAddress() { return addressService.toAddress( getLatLong() ); }             // <1>
-public void setAddress(String address) { setLatLong(addressService.toLatLong(address)); }
-
-@javax.jdo.annotations.Column
-private String latLong;
-@Programmatic
-public String getLatLong() { return latLong; }                                              // <2>
-public void setLatLong(String latLong) { this.latLong = latLong; }
-
-@javax.inject.Inject
-AddressService addressService;                                                              // <3>
-----
-<1> the representation of the address, in human readable form, eg "10 Downing Street, London, UK"
-<2> the lat/long representation of the address, eg "51.503363;-0.127625"
-<3> an injected service that can convert to/from address and latLong.
-
-[[__ugfun_how-tos_class-structure_properties_mapping-strings]]
-== Mapping ``String``s (Length)
-
-By default JDO/DataNucleus will map string properties to a `VARCHAR(255)`.
-To limit the length, use the `@Column(length=...)` annotation.
-
-For example:
-
-[source,java]
-----
-@javax.jdo.annotations.Column(length=50)
-@lombok.Getter @lombok.Setter
-private String firstName
-----
-
-This is a good example of a case where Apache Isis infers domain semantics from the JDO annotation.
-
-
-
-[[__ugfun_how-tos_class-structure_properties_mapping-joda-dates]]
-== Mapping JODA Date
-
-Isis' JDO objectstore bundles DataNucleus' http://www.datanucleus.org/documentation/products/plugins.html[built-in support] for Joda `LocalDate` and `LocalDateTime` datatypes, meaning that entity properties of these types will be persisted as appropriate data types in the database tables.
-
-It is, however, necessary to annotate your properties with `@javax.jdo.annotations.Persistent`, otherwise the data won't actually be persisted.
-See the link:http://db.apache.org/jdo/field_types.html[JDO docs] for more details on this.
-
-Moreover, these datatypes are _not_ in the default fetch group, meaning that JDO/DataNucleus will perform an additional `SELECT` query for each attribute.
-To avoid this extra query, the annotation should indicate that the property is in the default fetch group.
-
-For example, the `ToDoItem` (in the https://github.com/isisaddons/isis-app-todoapp[todoapp example app] (not ASF)) defines the `dueBy` property as follows:
-
-[source,java]
-----
-@javax.jdo.annotations.Persistent(defaultFetchGroup="true")
-@javax.jdo.annotations.Column(allowsNull="true")
-@Getter @Setter
-private LocalDate dueBy;
-----
-
-[[__ugfun_how-tos_class-structure_properties_mapping-bigdecimals]]
-== Mapping ``BigDecimal``s (Precision)
-
-Working with `java.math.BigDecimal` properties takes a little care due to scale/precision issues.
-
-For example, suppose we have:
-
-[source,java]
-----
-@lombok.Getter @lombok.Setter
-private BigDecimal impact;
-----
-
-JDO/DataNucleus creates, at least with HSQL, the table with the field type as NUMERIC(19). No decimal digits are admitted. (Further details http://hsqldb.org/doc/2.0/guide/sqlgeneral-chapt.html#sgc_numeric_types[here]).
-
-What this implies is that, when a record is inserted, a log entry similar to this one appears:
-
-[source,java]
-----
-INSERT INTO ENTITY(..., IMPACT, ....) VALUES (...., 0.5, ....)
-----
-
-But when that same record is retrieved, the log will show that a value of "0" is returned, instead of 0.5.
-
-The solution is to explicitly add the scale to the field like this:
-
-[source,java]
-----
-@javax.jdo.annotations.Column(scale=2)
-@lombok.Getter @lombok.Setter
-private BigDecimal impact;
-----
-
-In addition, you should also set the scale of the `BigDecimal`, using `setScale(scale, roundingMode)`.
-
-More information can be found http://www.opentaps.org/docs/index.php/How_to_Use_Java_BigDecimal:_A_Tutorial[here] and http://www.tutorialspoint.com/java/math/bigdecimal_setscale_rm_roundingmode.htm[here].
-
-
-[[__ugfun_how-tos_class-structure_properties_mapping-blobs-and-clobs]]
-== Mapping ``Blob``s and ``Clob``s
-
-Apache Isis configures JDO/DataNucleus so that the properties of type `org.apache.isis.applib.value.Blob` and `org.apache.isis.applib.value.Clob` can also be persisted.
-
-As for xref:../ugfun/ugfun.adoc#__ugfun_how-tos_class-structure_properties_mapping-joda-dates[Joda dates], this requires the `@javax.jdo.annotations.Persistent` annotation.
-However, whereas for dates one would always expect this value to be retrieved eagerly, for blobs and clobs it is not so clear cut.
-
-[[__ugfun_how-tos_class-structure_properties_mapping-blobs-and-clobs_mapping-blobs]]
-=== Mapping ``Blob``s
-
-For example, in the `ToDoItem` class (of the https://github.com/isisaddons/isis-app-todoapp/blob/0333852ddd18ad67e3356fccf805aa442246790d/dom/src/main/java/todoapp/dom/todoitem/ToDoItem.java#L442[todoapp example app] (non-ASF) the `attachment` property is as follows:
-
-[source,java]
-----
-@javax.jdo.annotations.Persistent(defaultFetchGroup="false", columns = {
-    @javax.jdo.annotations.Column(name = "attachment_name"),
-    @javax.jdo.annotations.Column(name = "attachment_mimetype"),
-    @javax.jdo.annotations.Column(name = "attachment_bytes", jdbcType="BLOB", sqlType = "LONGVARBINARY")
-})
-@Property(
-        optionality = Optionality.OPTIONAL
-)
-@lombok.Getter @lombok.Setter
-private Blob attachment;
-----
-
-The three `@javax.jdo.annotations.Column` annotations are required because the mapping classes that Apache Isis provides (https://github.com/apache/isis/blob/isis-1.4.0/component/objectstore/jdo/jdo-datanucleus/src/main/java/org/apache/isis/objectstore/jdo/datanucleus/valuetypes/IsisBlobMapping.java#L59[IsisBlobMapping] and https://github.com/apache/isis/blob/isis-1.4.0/component/objectstore/jdo/jdo-datanucleus/src/main/java/org/apache/isis/objectstore/jdo/datanucleus/valuetypes/IsisClobMapping.java#L59[IsisClobMapping]) map to 3 columns.
-(It is not an error to omit these `@Column` annotations, but without them the names of the table columns are simply suffixed `_0`, `_1`, `_2` etc.
-
-If the `Blob` is mandatory, then use:
-
-[source,java]
-----
-@javax.jdo.annotations.Persistent(defaultFetchGroup="false", columns = {
-    @javax.jdo.annotations.Column(name = "attachment_name", allowsNull="false"),
-    @javax.jdo.annotations.Column(name = "attachment_mimetype", allowsNull="false"),
-    @javax.jdo.annotations.Column(name = "attachment_bytes",
-                                  jdbcType="BLOB", sqlType = "LONGVARBINARY",
-                                  allowsNull="false")
-})
-@Property(
-    optionality = Optionality.MANDATORY
-)
-@lombok.Getter @lombok.Setter
-private Blob attachment;
-----
-
-[NOTE]
-====
-If specifying a `sqlType` of "LONGVARBINARY" does not work, try instead "BLOB".
-There can be differences in behaviour between JDBC drivers.
-====
-
-[[__ugfun_how-tos_class-structure_properties_mapping-blobs-and-clobs_mapping-clobs]]
-=== Mapping ``Clob``s
-
-Mapping `Clob`s works in a very similar way, but the `jdbcType` and `sqlType` attributes will, respectively, be `CLOB` and `LONGVARCHAR`:
-
-[source,java]
-----
-@javax.jdo.annotations.Persistent(defaultFetchGroup="false", columns = {
-    @javax.jdo.annotations.Column(name = "attachment_name"),
-    @javax.jdo.annotations.Column(name = "attachment_mimetype"),
-    @javax.jdo.annotations.Column(name = "attachment_chars",
-                                  jdbcType="CLOB", sqlType = "LONGVARCHAR")
-})
-private Clob doc;
-@Property(
-    optionality = Optionality.OPTIONAL
-)
-public Clob getDoc() {
-    return doc;
-}
-public void setDoc(final Clob doc) {
-    this.doc = doc;
-}
-----
-
-[NOTE]
-====
-If specifying a `sqlType` of "LONGVARCHAR" does not work, try instead "CLOB".  There can be differences in behaviour between JDBC drivers.
-====
-
-[[__ugfun_how-tos_class-structure_properties_mapping-blobs-and-clobs_mapping-to-varbinary-or-varchar]]
-=== Mapping to VARBINARY or VARCHAR
-
-Instead of mapping to a sqlType of `LONGVARBINARY` (or perhaps `BLOB`), you might instead decide to map to a `VARBINARY`.
-The difference is whether the binary data is held "on-row" or as a pointer "off-row"; with a `VARBINARY` the data is held on-row and so you will need to specify a length.
-
-For example:
-
-[source,java]
-----
-@javax.jdo.annotations.Column(name = "attachment_bytes", jdbcTypr="BLOB", sqlType = "VARBINARY", length=2048)
-----
-
-The same argument applies to `LONGVARCHAR` (or `CLOB`); you could instead map to a regular `VARCHAR`:
-
-[source,java]
-----
-@javax.jdo.annotations.Column(name = "attachment_chars", sqlType = "VARCHAR", length=2048)
-----
-Support and maximum allowed length will vary by database vendor.
-
-
-
-[[__ugfun_how-tos_class-structure_properties_handling-mandatory-properties-in-subtypes]]
-== Handling Mandatory Properties in Subtypes
-
-If you have a hierarchy of classes then you need to decide which inheritance strategy to use.
-
-* "table per hierarchy", or "rollup" (`InheritanceStrategy.SUPERCLASS_TABLE`) +
-+
-whereby a single table corresponds to the superclass, and also holds the properties of the subtype (or subtypes) being rolled up
-
-* "table per class" (`InheritanceStrategy.NEW_TABLE`) +
-+
-whereby there is a table for both superclass and subclass, in 1:1 correspondence
-
-* "rolldown" (`InheritanceStrategy.SUBCLASS_TABLE`) +
-+
-whereby a single table holds the properties of the subtype, and also holds the properties of its supertype
-
-In the first "rollup" case, we can have a situation where - logically speaking - the property is mandatory in the subtype - but it must be mapped as nullable in the database because it is n/a for any other subtypes that are rolled up.
-
-In this situation we must tell JDO that the column is optional, but to Apache Isis we want to enforce it being mandatory. This can be done using the `@Property(optionality=Optionality.MANDATORY)` annotation.
-
-For example:
-
-[source,java]
-----
-@javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.SUPER_TABLE)
-public class SomeSubtype extends SomeSuperType {
-    @javax.jdo.annotations.Column(allowsNull="true")
-    @Property(optionality=Optionality.MANDATORY)
-    @lombok.Getter @lombok.Setter
-    private LocalDate date;
-}
-----
-
-[TIP]
-====
-The `@Property(optionality=...)` annotation is equivalent to the older but still supported `@Optional` annotation and `@Mandatory` annotations.
-====
-

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_crud.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_crud.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_crud.adoc
deleted file mode 100644
index efa18bc..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_crud.adoc
+++ /dev/null
@@ -1,29 +0,0 @@
-[[_ugfun_how-tos_crud]]
-= Object Management (CRUD)
-: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/
-
-NOTE: FIXME
-
-
-## Instantiating and Persisting Objects
-
-NOTE: FIXME - using ``DomainObjectContainer``'s support for  xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-creation-api[creation] and xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-persistence-api[persistence]
-
-## Finding Objects
-
-NOTE: FIXME - using xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer_generic-repository-api[`DomainObjectContainer`]
-
-### Using DataNucleus type-safe queries
-
-NOTE: FIXME - as described xref:../rgsvc/rgsvc.adoc#__rgsvc_api_IsisJdoSupport_type-safe-jdoql-queries[here]
-
-
-
-## Deleting Objects
-
-NOTE: FIXME using ``DomainObjectContainer``'s support for  xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-persistence-api[persistence]
-
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_derived-members.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_derived-members.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_derived-members.adoc
deleted file mode 100644
index abcf5e9..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_derived-members.adoc
+++ /dev/null
@@ -1,48 +0,0 @@
-[[_ugfun_how-tos_derived-members]]
-= Derived Members
-: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/
-
-NOTE: FIXME
-
-
-
-
-== Derived Property
-
-NOTE: FIXME
-
-
-
-
-== Derived Collection
-
-NOTE: FIXME
-
-While derived properties and derived collections typically "walk the graph" to associated objects, there is nothing to prevent the returned value being the result of invoking a repository (domain service) action.
-
-For example:
-
-[source,java]
-----
-public class Customer {
-    ...
-    public List<Order> getMostRecentOrders() {
-        return orderRepo.findMostRecentOrders(this, 5);
-    }
-}
-----
-
-
-
-
-== Trigger on property change
-
-NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_modify[`modify...()`], xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_clear[`clear...()`]
-
-
-
-== Trigger on collection change
-
-NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_addTo[`addTo...()`], xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_removeFrom[`removeFrom...()`]

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_domain-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_domain-services.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_domain-services.adoc
deleted file mode 100644
index 4159152..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_domain-services.adoc
+++ /dev/null
@@ -1,312 +0,0 @@
-[[_ugfun_how-tos_domain-services]]
-= Domain Services
-: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/
-
-
-
-
-In Apache Isis domain services have several responsibilities:
-
-- to expose actions to be rendered in the menu
-- to provide actions that are rendered as contributed actions/properties/collections on the contributee domain object
-- they act as subscribers to the event bus
-- they act as repositories (find existing objects) or as factories (create new objects)
-- they provide other services (eg performing calculations, attach a barcode, send an email etc).
-- to implement an SPI of the framework, most notably cross-cutting concerns such as security, command profiling, auditing and publishing.
-
-It's worth extending the xref:../ugfun/ugfun.adoc#_ugfun_core-concepts_philosophy_hexagonal-architecture[Hexagonal Architecture] to show where domain services -- and in particular the domain services provided by link:http://www.isisaddons.org[Isis Addons] (non-ASF) -- fit in:
-
-.The hexagonal architecture with Isis addons
-image::{_imagesdir}how-tos/domain-services/hexagonal-architecture-addons.png[width="700px"]
-
-The (non-ASF) link:http://isisaddons.org[Isis Addons] are a good source of domain services, providing SPI implementations of the common cross-cutting concerns, and also a number of APIs for domain objects to invoke (eg tags, excel, settings).  Of course, you can also write your own domain services as well, for example to interface with some external CMS system, say.
-
-The Apache Isis framework also provides numerous in-built domain services.  These are catalogued in the xref:../rgsvc/rgsvc.adoc[domain services] reference guide.
-
-
-
-[[__ugfun_how-tos_domain-services_organizing-services]]
-== Organizing Services
-
-In larger applications we have found it worthwhile to ensure that our domain services only act aligned with these responsibilities, employing a naming convention so that it is clear what the responsibilities of each domain service is.
-
-The application provides the `@DomainService(nature=...)` annotation that helps distinguish some of these responsibilities:
-
-- `VIEW` indicates that the actions should appear both on the menu and also be used as contributions
-- `VIEW_MENU_ONLY` indicates that the actions should appear on the menu
-- `VIEW_CONTRIBUTIONS_ONLY` indicates that the actions should not appear on the menu
-- `DOMAIN` indicates that the actions are for other domain objects to invoke (either directly or indirectly through the event bus), but in any case should not be rendered at all in the UI
-
-Pulling all the above together, here are our suggestions as to how you should organize your domain services.
-
-
-=== Factory and Repository
-
-The factory/repository uses an injected `DomainObjectContainer` to both instantiate new objects and to query the database for existing objects of a given entity type.  It is not visible in UI, rather other services delegate to it.
-
-We suggest naming such classes `XxxRepository`, eg:
-
-
-[source,java]
-----
-@DomainService(
-    nature=NatureOfService.DOMAIN                               // <1>
-)
-public CustomerRepository {
-    public List<Customer> findCustomerBy...(...) {
-        return allMatches(...);
-    }
-    public Customer newCustomer(...) {
-        Customer Customer = container.newTransientInstance(Customer.class);
-        ...
-        persistIfNotAlready(Customer);
-        return Customer;
-    }
-    public List<Customer> allCustomers() {
-        return container.allInstances(Customer.class);
-    }
-    @Inject
-    DomainObjectContainer container;
-}
-----
-<1> interacted with only programmatically by other objects in the domain layer.
-
-There is no need to annotate the actions; they are implicitly hidden because of the domain service's nature.
-
-
-
-=== Menu
-
-Menu services provide actions to be rendered on the menu.
-
-For the Wicket viewer, each service's actions appear as a collection of menu items of a named menu, and this menu is on one of the three menu bars provided by the Wicket viewer.  It is possible for more than one menu service's actions to appear on the same menu; a separator is shown between each.
-
-For the Restful Objects viewer, all menu services are shown in the services representation.
-
-We suggest naming such classes `XxxMenu`, eg:
-
-
-[source,java]
-----
-@DomainService(
-    nature = NatureOfService.VIEW_MENU_ONLY                     // <1>
-)
-@DomainServiceLayout(
-        named = "Customers",                                    // <2>
-        menuBar = DomainServiceLayout.MenuBar.PRIMARY,
-        menuOrder = "10"
-)
-public class CustomerMenu {
-    @Action(
-            semantics = SemanticsOf.SAFE
-    )
-    @MemberOrder( sequence = "1" )
-    public List<Customer> findCustomerBy...(...) {
-        return CustomerRepository.findCustomerBy(...);          // <3>
-    }
-
-    @Action(
-            semantics = SemanticsOf.NON_IDEMPOTENT
-    )
-    @MemberOrder( sequence = "3" )
-    public Customer newCustomer(...) {
-        return CustomerRepository.newCustomer(...);
-    }
-
-    @Action(
-            semantics = SemanticsOf.SAFE,
-            restrictTo = RestrictTo.PROTOTYPING
-    )
-    @MemberOrder( sequence = "99" )
-    public List<Customer> allCustomers() {
-        return CustomerRepository.allBankMandates();
-    }
-
-    @Inject
-    protected CustomerRepository customerRepository;
-}
-----
-<1> the service's actions should be rendered as menu items
-<2> specifies the menu name.  All services with the same menu name will be displayed on the same menu, with separators between
-<3> delegates to an injected repository.
-
-Not every action on the repository need to be delegated to of course (the above example does but only because it is very simple).
-
-[TIP]
-====
-Note also that while there's nothing to stop `VIEW_MENU` domain services being injected into other domain objects and interacted with programmatically, we recommend against it.  Instead, inject the underlying repository.  If there is additional business logic, then consider introducing a further `DOMAIN`-scoped service and call that instead.
-====
-
-
-
-=== Contributions
-
-Services can contribute either actions, properties or collections, based on the type of their parameters.
-
-We suggest naming such classes `XxxContributions`, eg:
-
-[source,java]
-----
-@DomainService(
-    nature=NatureOfService.VIEW_CONTRIBUTIONS_ONLY              // <1>
-)
-@DomainServiceLayout(
-    menuOrder="10",
-    name="...",
-}
-public OrderContributions {
-    @Action(semantics=SemanticsOf.SAFE)
-    @ActionLayout(contributed=Contributed.AS_ASSOCIATION)       // <2>
-    @CollectionLayout(render=RenderType.EAGERLY)
-    public List<Order> orders(Customer customer) {              // <3>
-        return container.allMatches(...);
-    }
-
-    @Inject
-    CustomerRepository customerRepository;
-}
-----
-<1> the service's actions should be contributed to the entities of the parameters of those actions
-<2> contributed as an association, in particular as a collection because returns a `List<T>`.
-<3> Only actions with a single argument can be contributed as associations
-
-More information about contributions can be found xref:../ugfun/ugfun.adoc#_ugfun_how-tos_contributed-members[here].  More information
-about using contributions and mixins to keep your domain application decoupled can be found xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_contributions[here] and xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_mixins[here].
-
-
-=== Event Subscribers
-
-Event subscribers can both veto interactions (hiding members, disabling members or validating changes), or can react to interactions (eg action invocation or property edit).
-
-We suggest naming such classes `XxxSubscriptions`, eg:
-
-[source,java]
-----
-@DomainService(
-    nature=NatureOfService.DOMAIN                       // <1>
-)
-@DomainServiceLayout(
-    menuOrder="10",
-    name="...",
-}
-public CustomerOrderSubscriptions {
-    @com.google.common.eventbus.Subscribe
-    public void on(final Customer.DeletedEvent ev) {
-        Customer customer = ev.getSource();
-        orderRepository.delete(customer);
-    }
-    @Inject
-    OrderRepository orderRepository;
-}
-----
-<1> subscriptions do not appear in the UI at all, so should use the domain nature of service
-
-
-
-== Prototyping
-
-While for long-term maintainability we do recommend the naming conventions described xref:../ugfun/ugfun.adoc#__ugfun_how-tos_domain-services_organizing-services[above], you can get away with far fewer services when just prototyping a domain.
-
-If the domain service nature is not specified (or is left to its default, `VIEW`), then the service's actions will
-appear in the UI both as menu items _and_ as contributions (and the service can of course be injected into other domain objects for programmatic invocation).
-
-Later on it is easy enough to refactor the code to tease apart the different responsibilities.
-
-
-
-
-== Scoped services
-
-By default all domain services are considered to be singletons, and thread-safe.
-
-Sometimes though a service's lifetime is applicable only to a single request; in other words it is request-scoped.
-
-The CDI annotation xref:../rgant/rgant.adoc#_rgant-RequestScoped[`@javax.enterprise.context.RequestScoped`] is used to indicate this fact:
-
-[source,java]
-----
-@javax.enterprise.context.RequestScoped
-public class MyService extends AbstractService {
-    ...
-}
-----
-
-The framework provides a number of request-scoped services, include a xref:../rgsvc/rgsvc.adoc#_rgsvc_api_Scratchpad[`Scratchpad`] service query results caching through the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_QueryResultsCache[`QueryResultsCache`], and support for co-ordinating bulk actions through the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ActionInvocationContext[`ActionInvocationContext`] service.  See the xref:../rgsvc/rgsvc.adoc[domain services] reference guide for further details.
-
-
-
-
-== Registering domain services
-
-The easiest way to register domain services is using xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`] to specify the modules
-which contain xref:../rgant/rgant.adoc#_rgant-DomainService[`@DomainService`]-annotated classes.
-
-For example:
-
-[source,ini]
-----
-public class MyAppManifest implements AppManifest {
-    public List<Class<?>> getModules() {
-        return Arrays.asList(
-                ToDoAppDomainModule.class,
-                ToDoAppFixtureModule.class,
-                ToDoAppAppModule.class,
-                org.isisaddons.module.audit.AuditModule.class);
-    }
-    ...
-}
-----
-
-will load all services in the packages underneath the four modules listed.
-
-An alternative (older) mechanism is to registered domain services in the `isis.properties` configuration file, under `isis.services` key (a comma-separated list); for example:
-
-[source,ini]
-----
-isis.services = com.mycompany.myapp.employee.Employees\,
-                com.mycompany.myapp.claim.Claims\,
-                ...
-----
-
-This will then result in the framework instantiating a single instance of each of the services listed.
-
-If all services reside under a common package, then the `isis.services.prefix` can specify this prefix:
-
-[source,ini]
-----
-isis.services.prefix = com.mycompany.myapp
-isis.services = employee.Employees,\
-                claim.Claims,\
-                ...
-----
-
-This is quite rare, however; you will often want to use default implementations of domain services that are provided by the framework and so will not reside under this prefix.
-
-Examples of framework-provided services (as defined in the applib) include clock, auditing, publishing, exception handling, view model support, snapshots/mementos, and user/application settings management; see the xref:../rgsvc/rgsvc.adoc[domain services] reference guide for further details.
-
-
-
-== Initialization
-
-Services can optionally declare lifecycle callbacks to initialize them (when the app is deployed) and to shut them down (when the app is undeployed).
-
-An Apache Isis session _is_ available when initialization occurs (so services can interact with the object store, for example).
-
-
-The framework will call any `public` method annotated with xref:../rgant/rgant.adoc#_rgant-PostConstruct[`@PostConstruct`] with either no arguments of an argument of type `Map<String,String>`
-
-or
-
-In the latter case, the framework passes in the configuration (`isis.properties` and any other component-specific configuration files).
-
-
-Shutdown is similar; the framework will call any method annotated with xref:../rgant/rgant.adoc#_rgant-PreDestroy[`@PreDestroy`].
-
-
-
-== The getId() method
-
-Optionally, a service may provide a xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_getId[`getId()`] method.  This method returns a logical identifier for a service, independent of its implementation.
-

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_drop-downs-and-defaults.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_drop-downs-and-defaults.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_drop-downs-and-defaults.adoc
deleted file mode 100644
index 9db7ccc..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_drop-downs-and-defaults.adoc
+++ /dev/null
@@ -1,65 +0,0 @@
-[[_ugfun_how-tos_drop-downs-and-defaults]]
-= Drop Downs and Defaults
-: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/
-
-NOTE: FIXME
-
-
-== For Properties
-
-NOTE: FIXME
-
-### Choices for Property
-
-NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`]
-
-### Auto-complete for property
-
-NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`]
-
-### Default for property
-
-NOTE: FIXME -  xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_default[`default...()`]
-
-
-
-
-== For Action Parameters
-
-NOTE: FIXME
-
-### Choices for action parameter
-
-NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`]
-
-### Dependent choices for action params
-
-NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`]
-
-### Auto-complete for action param
-
-NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`]
-
-### Default for action param
-
-NOTE: FIXME -  xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_default[`default...()`]
-
-
-
-
-
-== For both Properties and Action Parameters
-
-NOTE: FIXME
-
-
-### Drop-down for limited number of instances
-
-NOTE: FIXME - xref:../rgant/rgant.adoc#_rgant-DomainObject_bounded[`@DomainObject#bounded()`]
-
-
-### Auto-complete (repository-based)
-
-xref:../rgant/rgant.adoc#_rgant-DomainObject_autoCompleteRepository[`@DomainObject#autoCompleteRepository()`]

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_render-all-properties-in-tables.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_render-all-properties-in-tables.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_render-all-properties-in-tables.adoc
deleted file mode 100644
index fa370de..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_render-all-properties-in-tables.adoc
+++ /dev/null
@@ -1,49 +0,0 @@
-[[_ugfun_how-tos_render-all-properties-in-tables]]
-= Subclass properties in tables
-: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/
-
-
-
-Suppose you have a hierarchy of classes where a property is derived and abstract in the superclass, concrete implementations in the subclasses. For example:
-
-[source,java]
-----
-public abstract class LeaseTerm {
-    public abstract BigDecimal getEffectiveValue();
-    ...
-}
-
-public class LeaseTermForIndexableTerm extends LeaseTerm {
-    public BigDecimal getEffectveValue() { ... }
-    ...
-}
-----
-
-Currently the Wicket viewer will not render the property in tables (though the property is correctly rendered in views).
-
-[NOTE]
-====
-For more background on this workaround, see https://issues.apache.org/jira/browse/ISIS-582[ISIS-582].
-====
-
-The work-around is simple enough; make the method concrete in the superclass and return a dummy implementation, eg:
-
-[source,java]
-----
-public abstract class LeaseTerm {
-    public BigDecimal getEffectiveValue() {
-        return null;        // workaround for ISIS-582
-    }
-    ...
-}
-----
-
-
-Alternatively the implementation could throw a `RuntimeException`, eg
-
-[source,java]
-----
-throw new RuntimeException("never called; workaround for ISIS-582");
-----
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_simulating-collections-of-values.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_simulating-collections-of-values.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_simulating-collections-of-values.adoc
deleted file mode 100644
index 4402b7c..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_simulating-collections-of-values.adoc
+++ /dev/null
@@ -1,23 +0,0 @@
-[[_ugfun_how-tos_simulating-collections-of-values]]
-= Collections of values
-: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/
-
-
-
-Although in Apache Isis you can have properties of either values (string, number, date etc) or of (references to other) entities, with collections the framework (currently) only supports collections of (references to) entities.  That is, collections of values (a bag of numbers, say) are not supported.
-
-However, it is possible to simulate a bag of numbers using view models.
-
-
-== View Model
-
-NOTE: FIXME
-
-
-
-== Persistence Concerns
-
-NOTE: FIXME -  easiest to simply store using DataNucleus' support for collections, marked as xref:../rgant/rgant.adoc#_rgant-Programmatic[`@Programmatic`] so that it is ignored by Apache Isis.  Alternatively can store as json/xml in a varchar(4000) or clob and manually unpack.
-

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints.adoc
deleted file mode 100644
index be5a865..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints.adoc
+++ /dev/null
@@ -1,15 +0,0 @@
-[[_ugfun_how-tos_ui-hints]]
-= UI Hints
-: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/
-
-
-The Apache Isis programming model includes several mechanisms for a domain object to provide UI hints.  These range from their title (so an end-user can distinguish one object from another) through to hints that can impact their CSS styling.
-
-include::_ugfun_how-tos_ui-hints_object-titles-and-icons.adoc[leveloffset=+1]
-include::_ugfun_how-tos_ui-hints_names-and-descriptions.adoc[leveloffset=+1]
-include::_ugfun_how-tos_ui-hints_layout.adoc[leveloffset=+1]
-include::_ugfun_how-tos_ui-hints_eager-rendering.adoc[leveloffset=+1]
-include::_ugfun_how-tos_ui-hints_action-icons-and-css.adoc[leveloffset=+1]
-include::_ugfun_how-tos_ui_are-you-sure.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_action-icons-and-css.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_action-icons-and-css.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_action-icons-and-css.adoc
deleted file mode 100644
index 7c15e16..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_action-icons-and-css.adoc
+++ /dev/null
@@ -1,58 +0,0 @@
-[[_ugfun_how-tos_ui-hints_action-icons-and-css]]
-= Action Icons and CSS
-: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 allows link:http://fortawesome.github.io/Font-Awesome/icons/[font awesome] icons to be associated with each action, and for link:http://getbootstrap.com/css/#buttons[Bootstrap CSS] to be applied to action rendered as buttons.
-
-These UI hint can be applied either to individual actions, or can be applied en-masse using pattern matching.
-
-== Per action
-
-NOTE: FIXME - xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout#cssClass()`] and xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClassFa[`@ActionLayout#cssClassFa()`]
-
-
-Alternatively, you can specify these hints dynamically in the xref:../ugvw/ugvw.adoc#_ugvw_layout[`Xxx.layout.json`] for the entity.
-
-
-== Per pattern matching
-
-Rather than annotating every action with xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClassFa[`@ActionLayout#cssClassFa()`] and xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout#cssClass()`] you can instead specify the UI hint globally using regular expressions.
-
-The xref:../rgcfg/rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.reflector.facet.cssClassFa.patterns` is a comma separated list of key:value pairs, eg:
-
-[source,ini]
-----
-isis.reflector.facet.cssClassFa.patterns=\
-                        new.*:fa-plus,\
-                        add.*:fa-plus-square,\
-                        create.*:fa-plus,\
-                        list.*:fa-list, \
-                        all.*:fa-list, \
-                        download.*:fa-download, \
-                        upload.*:fa-upload, \
-                        execute.*:fa-bolt, \
-                        run.*:fa-bolt
-----
-
-where the key is a regex matching action names (eg `create.*`) and the value is a link:http://fortawesome.github.io/Font-Awesome/icons/[font-awesome] icon name (eg `fa-plus`) to be applied (as per `@CssClassFa()`) to all action members matching the regex.
-
-
-Similarly, the xref:../rgcfg/rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.reflector.facet.cssClass.patterns` is a comma separated list of key:value pairs, eg:
-
-[source,ini]
-----
-isis.reflector.facet.cssClass.patterns=\
-                        delete.*:btn-warning
-----
-
-where (again)the key is a regex matching action names (eg `delete.*`) and the value is a link:http://getbootstrap.com/css/[Bootstrap] CSS button class (eg `btn-warning) to be applied (as per `@CssClass()`) to all action members matching the regex.
-
-[TIP]
-====
-We strongly recommend that you use this technique rather than annotating each action with xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClassFa[`@ActionLayout#cssClassFa()`] or xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout#cssClass()`].  Not only is the code more maintainable, you'll also find that it forces you to be consistent in your action names.
-====
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_eager-rendering.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_eager-rendering.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_eager-rendering.adoc
deleted file mode 100644
index 7ef9e66..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_eager-rendering.adoc
+++ /dev/null
@@ -1,58 +0,0 @@
-[[_ugfun_how-tos_ui-hints_eager-rendering]]
-= Eager rendering
-: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/
-
-
-By default, collections all rendered lazily, in other words in a "collapsed" table view:
-
-NOTE: FIXME - screenshot here
-
-For the more commonly used collections we want to show the table expanded:
-
-NOTE: FIXME - screenshot here
-
-For this we annotate the collection using the `@CollectionLayout(render=RenderType.EAGERLY`; for example
-
-[source,java]
-----
-@javax.jdo.annotations.Persistent(table="ToDoItemDependencies")
-private Set<ToDoItem> dependencies = new TreeSet<>();
-@Collection
-@CollectionLayout(
-    render = RenderType.EAGERLY
-)
-public Set<ToDoItem> getDependencies() {
-    return dependencies;
-}
-----
-
-Alternatively, it can be specified the `Xxx.layout.json` file:
-
-[source,javascript]
-----
-"dependencies": {
-    "collectionLayout": {
-        "render": "EAGERLY"
-    },
-}
-----
-
-[WARNING]
-====
-It might be thought that collections that are eagerly rendered should also be eagerly loaded from the database by enabling the `defaultFetchGroup` attribute:
-
-[source,java]
-----
-@javax.jdo.annotations.Persistent(table="ToDoItemDependencies", defaultFetchGroup="true")
-private Set<ToDoItem> dependencies = new TreeSet<>();
-...
-----
-
-While this can be done, it's likely to be a bad idea, because doing so will cause DataNucleus to query for more data than required even if the object is being rendered within some referencing object's table.
-
-Of course, your mileage may vary, so don't think you can't experiment.
-====
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_layout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_layout.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_layout.adoc
deleted file mode 100644
index a4b02a1..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_layout.adoc
+++ /dev/null
@@ -1,9 +0,0 @@
-[[_ugfun_how-tos_ui-hints_layout]]
-= Layout
-: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/
-
-
-See the xref:../ugvw/ugvw.adoc#_ugvw_layout[object layout] chapter.
-

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_names-and-descriptions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_names-and-descriptions.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_names-and-descriptions.adoc
deleted file mode 100644
index 0b9e432..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_names-and-descriptions.adoc
+++ /dev/null
@@ -1,47 +0,0 @@
-[[_ugfun_how-tos_ui-hints_names-and-descriptions]]
-= Names and Descriptions
-: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/
-
-NOTE: FIXME
-
-
-
-NOTE: see also xref:../ugbtb/ugbtb.adoc#_ugbtb_i18n[Internationalization]
-
-== Class (object)
-
-NOTE: FIXME - xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_named[`@DomainObjectLayout#named()`], xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_describedAs[`@DomainObjectLayout#describedAs()`]
-
-
-== Property
-
-NOTE: FIXME - xref:../rgant/rgant.adoc#_rgant-PropertyLayout_named[`@PropertyLayout#named()`], xref:../rgant/rgant.adoc#_rgant-PropertyLayout_describedAs[`@PropertyLayout#describedAs()`]
-
-
-
-== Collections
-
-NOTE: FIXME - xref:../rgant/rgant.adoc#_rgant-CollectionLayout_named[`@CollectionLayout#named()`], xref:../rgant/rgant.adoc#_rgant-CollectionLayout_describedAs[`@CollectionLayout#describedAs()`]
-
-
-
-== Actions
-
-NOTE: FIXME - xref:../rgant/rgant.adoc#_rgant-ActionLayout_named[`@ActionLayout#named()`], xref:../rgant/rgant.adoc#_rgant-ActionLayout_describedAs[`@ActionLayout#describedAs()`]
-
-
-== Action Parameters
-
-NOTE: FIXME - xref:../rgant/rgant.adoc#_rgant-ParameterLayout_named[`@ParameterLayout#named()`], xref:../rgant/rgant.adoc#_rgant-ParameterLayout_describedAs[`@ParameterLayout#describedAs()`]
-
-
-[TIP]
-====
-If you're running on Java 8, then note that it's possible to write Isis applications without using `@ParameterLayout(named=...)` annotation.  Support for this can be found in the link:http://github.com/isisaddons/isis-metamodel-paraname8[Isis addons' paraname8] metamodel extension (non-ASF).  (In the future we'll fold this into core).  See also our guidance on xref:release-notes.adoc#_migration-notes_1.8.0-to-1.9.0_upgrading-to-java8[upgrading to Java 8].
-====
-
-
-
-

[12/58] [abbrv] isis git commit: ISIS-1521: fixes xref links between guides

[da...@apache.org]

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout.adoc
index 838d598..6761765 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout.adoc
@@ -19,32 +19,32 @@ The table below summarizes the annotation's attributes.
 | Description
 
 
-|xref:rgant.adoc#_rgant-ParameterLayout_cssClass[`cssClass()`]
+|xref:../rgant/rgant.adoc#_rgant-ParameterLayout_cssClass[`cssClass()`]
 |Any string valid as a CSS class
-|the css class that a parameter should have, to allow more targetted styling in xref:rgcfg.adoc#_rgcfg_application-specific_application-css[`application.css`]
+|the css class that a parameter should have, to allow more targetted styling in xref:../rgcfg/rgcfg.adoc#_rgcfg_application-specific_application-css[`application.css`]
 
 
-|xref:rgant.adoc#_rgant-ParameterLayout_describedAs[`describedAs()`]
+|xref:../rgant/rgant.adoc#_rgant-ParameterLayout_describedAs[`describedAs()`]
 |String
 |description of this parameter, eg to be rendered in a tooltip.
 
 
-|xref:rgant.adoc#_rgant-ParameterLayout_labelPosition[`labelPosition()`]
+|xref:../rgant/rgant.adoc#_rgant-ParameterLayout_labelPosition[`labelPosition()`]
 |`LEFT`, `TOP`, `RIGHT`, `NONE` +
 (`LEFT`)
 |in forms, the positioning of the label relative to the property value. +
 
-Default is `LEFT`, unless xref:rgant.adoc#_rgant-ParameterLayout_multiLine[`multiLine`] in which case `TOP`.  The value `RIGHT` is only supported for boolean parameters.
+Default is `LEFT`, unless xref:../rgant/rgant.adoc#_rgant-ParameterLayout_multiLine[`multiLine`] in which case `TOP`.  The value `RIGHT` is only supported for boolean parameters.
 
 
-|xref:rgant.adoc#_rgant-ParameterLayout_multiLine[`multiLine()`]
+|xref:../rgant/rgant.adoc#_rgant-ParameterLayout_multiLine[`multiLine()`]
 |Positive integer
 |for string parameters, render as a text area over multiple lines. +
 
-If set > 1, then then xref:rgant.adoc#_rgant-ParameterLayout_labelPosition[`labelPosition`] defaults to `TOP`.
+If set > 1, then then xref:../rgant/rgant.adoc#_rgant-ParameterLayout_labelPosition[`labelPosition`] defaults to `TOP`.
 
 
-|xref:rgant.adoc#_rgant-ParameterLayout_named[`named()`]
+|xref:../rgant/rgant.adoc#_rgant-ParameterLayout_named[`named()`]
 |String
 |the name of this parameter. +
 
@@ -56,12 +56,12 @@ For Java 7 this is generally required. For Java 8, the name can often be inferre
 |whether to HTML escape the name of this parameter.
 
 
-|xref:rgant.adoc#_rgant-ParameterLayout_renderedAsDayBefore[`renderedAsDayBefore()`]
+|xref:../rgant/rgant.adoc#_rgant-ParameterLayout_renderedAsDayBefore[`renderedAsDayBefore()`]
 |
 |for date parameters only, render the date as one day prior to the actually stored date (eg the end date of an open interval into a closed interval)
 
 
-|xref:rgant.adoc#_rgant-ParameterLayout_typicalLength[`typicalLength()`]
+|xref:../rgant/rgant.adoc#_rgant-ParameterLayout_typicalLength[`typicalLength()`]
 |
 |the typical entry length of a field, use to determine the optimum width for display
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_cssClass.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_cssClass.adoc
index 277b586..5ba4b7e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_cssClass.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_cssClass.adoc
@@ -7,9 +7,9 @@
 
 
 
-The `cssClass()` attribute can be used to render additional CSS classes in the HTML (a wrapping `<div>`) that represents the action parameter.   xref:rgcfg.adoc#_rgcfg_application-specific_application-css[Application-specific CSS] can then be used to target and adjust the UI representation of that particular element.
+The `cssClass()` attribute can be used to render additional CSS classes in the HTML (a wrapping `<div>`) that represents the action parameter.   xref:../rgcfg/rgcfg.adoc#_rgcfg_application-specific_application-css[Application-specific CSS] can then be used to target and adjust the UI representation of that particular element.
 
-This attribute can also be applied to xref:rgant.adoc#_rgant-DomainObjectLayout_cssClass[domain objects], xref:rgant.adoc#_rgant-ViewModelLayout_cssClass[view models], xref:rgant.adoc#_rgant-ActionLayout_cssClass[actions] xref:rgant.adoc#_rgant-PropertyLayout_cssClass[properties],  xref:rgant.adoc#_rgant-CollectionLayout_cssClass[collections] and xref:rgant.adoc#_rgant-ParameterLayout_cssClass[parameters].
+This attribute can also be applied to xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_cssClass[domain objects], xref:../rgant/rgant.adoc#_rgant-ViewModelLayout_cssClass[view models], xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClass[actions] xref:../rgant/rgant.adoc#_rgant-PropertyLayout_cssClass[properties],  xref:../rgant/rgant.adoc#_rgant-CollectionLayout_cssClass[collections] and xref:../rgant/rgant.adoc#_rgant-ParameterLayout_cssClass[parameters].
 
 For example:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_describedAs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_describedAs.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_describedAs.adoc
index 6c1e285..b4ab0da 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_describedAs.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_describedAs.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-The `describedAs()` attribute is used to provide a short description of the action parameter to the user.  In the xref:ugvw.adoc#[Wicket viewer] it is displayed as a 'tool tip'.  The `describedAs()` attribute can also be specified for xref:rgant.adoc#_rgant-CollectionLayout_describedAs[collections],  xref:rgant.adoc#_rgant-PropertyLayout_describedAs[properties], xref:rgant.adoc#_rgant-ActionLayout_describedAs[actions], xref:rgant.adoc#_rgant-DomainObjectLayout_describedAs[domain objects] and xref:rgant.adoc#_rgant-ViewModelLayout_describedAs[view models].
+The `describedAs()` attribute is used to provide a short description of the action parameter to the user.  In the xref:ugvw.adoc#[Wicket viewer] it is displayed as a 'tool tip'.  The `describedAs()` attribute can also be specified for xref:../rgant/rgant.adoc#_rgant-CollectionLayout_describedAs[collections],  xref:../rgant/rgant.adoc#_rgant-PropertyLayout_describedAs[properties], xref:../rgant/rgant.adoc#_rgant-ActionLayout_describedAs[actions], xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_describedAs[domain objects] and xref:../rgant/rgant.adoc#_rgant-ViewModelLayout_describedAs[view models].
 
 Descriptions may be provided for objects, members (properties,
 collections and actions), and for individual parameters within an action

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_labelPosition.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_labelPosition.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_labelPosition.adoc
index 5a7a017..0242245 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_labelPosition.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_labelPosition.adoc
@@ -6,9 +6,9 @@
 
 
 
-The `labelPosition()` attribute determines the positioning of labels for parameters.  This attribute can also be specified for xref:rgant.adoc#_rgant-PropertyLayout_labelPosition[properties].
+The `labelPosition()` attribute determines the positioning of labels for parameters.  This attribute can also be specified for xref:../rgant/rgant.adoc#_rgant-PropertyLayout_labelPosition[properties].
 
-The positioning of labels is typically `LEFT`, but can be positioned to the `TOP`.  The one exception is xref:rgant.adoc#_rgant-ParameterLayout_multiLine[`multiLine()`] string parameters, where the label defaults to `TOP` automatically (to provide as much real-estate for the multiline text field as possible).
+The positioning of labels is typically `LEFT`, but can be positioned to the `TOP`.  The one exception is xref:../rgant/rgant.adoc#_rgant-ParameterLayout_multiLine[`multiLine()`] string parameters, where the label defaults to `TOP` automatically (to provide as much real-estate for the multiline text field as possible).
 
 For boolean parameters a positioning of `RIGHT` is also allowed; this is ignored for all other types.
 
@@ -36,6 +36,6 @@ public class Order {
 ----
 
 
-To get an idea of how these are rendered (in the xref:ugvw.adoc#[Wicket viewer]), see xref:rgant.adoc#_rgant-PropertyLayout_labelPosition[PropertyLayout#labelPosition()].
+To get an idea of how these are rendered (in the xref:ugvw.adoc#[Wicket viewer]), see xref:../rgant/rgant.adoc#_rgant-PropertyLayout_labelPosition[PropertyLayout#labelPosition()].
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_multiLine.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_multiLine.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_multiLine.adoc
index 5746439..18ff449 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_multiLine.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_multiLine.adoc
@@ -6,7 +6,7 @@
 
 
 
-The `multiLine()` attribute specifies that the text field for a string parameter should span multiple lines.  It is ignored for other parameter types.  The attribute is also supported for xref:rgant.adoc#_rgant-PropertyLayout_multiLine[properties].
+The `multiLine()` attribute specifies that the text field for a string parameter should span multiple lines.  It is ignored for other parameter types.  The attribute is also supported for xref:../rgant/rgant.adoc#_rgant-PropertyLayout_multiLine[properties].
 
 For example:
 
@@ -27,6 +27,6 @@ public class BugReport {
 
 [NOTE]
 ====
-If set > 1 (as would normally be the case), then the default xref:rgant.adoc#_rgant-ParameterLayout_labelPosition[`labelPosition`] defaults to `TOP` (rather than `LEFT`, as would normally be the case).
+If set > 1 (as would normally be the case), then the default xref:../rgant/rgant.adoc#_rgant-ParameterLayout_labelPosition[`labelPosition`] defaults to `TOP` (rather than `LEFT`, as would normally be the case).
 ====
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_named.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_named.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_named.adoc
index 3b589d0..b34662f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_named.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_named.adoc
@@ -6,11 +6,11 @@
 
 
 
-The `named()` attribute explicitly specifies the action parameter's name. This attribute can also be specified for xref:rgant.adoc#_rgant-ActionLayout_named[actions], xref:rgant.adoc#_rgant-CollectionLayout_named[collections], xref:rgant.adoc#_rgant-PropertyLayout_named[properties], xref:rgant.adoc#_rgant-DomainObjectLayout_named[domain objects], xref:rgant.adoc#_rgant-ViewModelLayout_named[view models] and xref:rgant.adoc#_rgant-DomainServiceLayout_named[domain services].
+The `named()` attribute explicitly specifies the action parameter's name. This attribute can also be specified for xref:../rgant/rgant.adoc#_rgant-ActionLayout_named[actions], xref:../rgant/rgant.adoc#_rgant-CollectionLayout_named[collections], xref:../rgant/rgant.adoc#_rgant-PropertyLayout_named[properties], xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_named[domain objects], xref:../rgant/rgant.adoc#_rgant-ViewModelLayout_named[view models] and xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_named[domain services].
 
 Unlike most other aspects of the Apache Isis metamodel, the name of method parameters cannot (prior to Java 8, at least) be inferred from the Java source code.  Without other information, Apache Isis uses the object's type (`int`, `String` etc) as the name instead.  This can be sufficient for application-specific reference types (eg `ToDoItem`) but is generally not sufficient for primitives and other value types.
 
-The `named()` attribute (or the xref:rgant.adoc#_rgant-aaa_deprecated[deprecated `@Named`] annotation) is therefore often required to specify the parameter name.
+The `named()` attribute (or the xref:../rgant/rgant.adoc#_rgant-aaa_deprecated[deprecated `@Named`] annotation) is therefore often required to specify the parameter name.
 
 As of Java 8, the Java reflection API has been extended.  The (non-ASF) http://github.com/isisaddons/isis-metamodel-paraname8[Isis addons' paraname8] metamodel extension provides support for this.  Note that your application must (obviously) be running on Java 8, and be compiled with the `-parameters` compile flag for javac.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_renderedAsDayBefore.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_renderedAsDayBefore.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_renderedAsDayBefore.adoc
index ccf9540..8bf1fd5 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_renderedAsDayBefore.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_renderedAsDayBefore.adoc
@@ -6,7 +6,7 @@
 
 
 
-The `renderedAsDayBefore()` attribute applies only to date parameters whereby the date will be rendered as the day before the value actually held in the domain object.  It is ignored for parameters of other types.  This attribute is also supported for xref:rgant.adoc#_rgant-PropertyLayout_renderedAsDayBefore[properties].
+The `renderedAsDayBefore()` attribute applies only to date parameters whereby the date will be rendered as the day before the value actually held in the domain object.  It is ignored for parameters of other types.  This attribute is also supported for xref:../rgant/rgant.adoc#_rgant-PropertyLayout_renderedAsDayBefore[properties].
 
 This behaviour might at first glance appear odd, but the rationale is to support the use case of a sequence of instances that represent adjacent intervals of time.  In such cases there would typically be `startDate` and `endDate` properties, eg for all of Q2.  Storing this as a half-closed interval -- eg `[1-Apr-2015, 1-July-2015)` -- can substantially simplify internal algorithms; the `endDate` of one interval will correspond to the `startDate` of the next.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_typicalLength.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_typicalLength.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_typicalLength.adoc
index 120da18..bcc9c7c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_typicalLength.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_typicalLength.adoc
@@ -6,7 +6,7 @@
 
 
 
-The `typicalLength()` attribute indicates the typical length of a string parameter.  It is ignored for parameters of other types.  The attribute is also supported for xref:rgant.adoc#_rgant-PropertyLayout_typicalLength[properties].
+The `typicalLength()` attribute indicates the typical length of a string parameter.  It is ignored for parameters of other types.  The attribute is also supported for xref:../rgant/rgant.adoc#_rgant-PropertyLayout_typicalLength[properties].
 
 The information is intended as a hint to the UI to determine the space that should be given to render a particular string parameter.  That said, note that the xref:ugvw.adoc#[Wicket viewer] uses the maximum space available for all fields, so in effect ignores this attribute.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Parameter_fileAccept.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Parameter_fileAccept.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Parameter_fileAccept.adoc
index f16f13d..e309616 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Parameter_fileAccept.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Parameter_fileAccept.adoc
@@ -6,9 +6,9 @@
 
 
 
-The `fileAccept()` attribute applies only to xref:rgcms.adoc#_rgcms_classes_value-types_Blob[`Blob`]
-or xref:rgcms.adoc#_rgcms_classes_value-types_Clob[`Clob`] parameters, indicating the type of file to accept when
-uploading a new value.   The attribute is also supported on xref:rgant.adoc#_rgant-Property_fileAccept[properties].
+The `fileAccept()` attribute applies only to xref:../rgcms/rgcms.adoc#_rgcms_classes_value-types_Blob[`Blob`]
+or xref:../rgcms/rgcms.adoc#_rgcms_classes_value-types_Clob[`Clob`] parameters, indicating the type of file to accept when
+uploading a new value.   The attribute is also supported on xref:../rgant/rgant.adoc#_rgant-Property_fileAccept[properties].
 
 For example:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Parameter_maxLength.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Parameter_maxLength.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Parameter_maxLength.adoc
index 10d6548..5baa3e4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Parameter_maxLength.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Parameter_maxLength.adoc
@@ -6,7 +6,7 @@
 
 
 
-The `maxLength()` attribute applies only to `String` parameters, indicating the maximum number of characters that the user may enter (for example in a text field in the UI).  It is ignored if applied to parameters of any other type.  This attribute can also be applied to xref:rgant.adoc#_rgant-Property_maxLength[properties].
+The `maxLength()` attribute applies only to `String` parameters, indicating the maximum number of characters that the user may enter (for example in a text field in the UI).  It is ignored if applied to parameters of any other type.  This attribute can also be applied to xref:../rgant/rgant.adoc#_rgant-Property_maxLength[properties].
 
 For example:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Parameter_mustSatisfy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Parameter_mustSatisfy.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Parameter_mustSatisfy.adoc
index de288f0..0a7643e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Parameter_mustSatisfy.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Parameter_mustSatisfy.adoc
@@ -6,11 +6,11 @@
 
 
 
-The `mustSatisfy()` attribute allows arbitrary validation to be applied to parameters using an (implementation of a) `org.apache.isis.applib.spec.Specification` object.  The attribute is also supported on xref:rgant.adoc#_rgant-Property_mustSatisfy[properties].
+The `mustSatisfy()` attribute allows arbitrary validation to be applied to parameters using an (implementation of a) `org.apache.isis.applib.spec.Specification` object.  The attribute is also supported on xref:../rgant/rgant.adoc#_rgant-Property_mustSatisfy[properties].
 
 [TIP]
 ====
-The specification implementations can (of course) be reused between parameters and xref:rgant.adoc#_rgant-Property_mustSatisfy[properties].
+The specification implementations can (of course) be reused between parameters and xref:../rgant/rgant.adoc#_rgant-Property_mustSatisfy[properties].
 ====
 
 The `Specification` is consulted during validation, being passed the proposed value.  If the proposed value fails, then the value returned is the used as the invalidity reason.

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Parameter_optionality.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Parameter_optionality.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Parameter_optionality.adoc
index 7715a9e..9d59d04 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Parameter_optionality.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Parameter_optionality.adoc
@@ -7,7 +7,7 @@
 
 
 
-By default, Apache Isis assumes that all parameters of an action are required (mandatory).  The `optionality()` attribute allows this to be relaxed.  The attribute is also supported for xref:rgant.adoc#_rgant-Property_optionality[properties].
+By default, Apache Isis assumes that all parameters of an action are required (mandatory).  The `optionality()` attribute allows this to be relaxed.  The attribute is also supported for xref:../rgant/rgant.adoc#_rgant-Property_optionality[properties].
 
 
 [TIP]
@@ -38,5 +38,5 @@ public class Customer {
 
 [NOTE]
 ====
-It is also possible to specify optionality using xref:rgant.adoc#_rgant_Nullable[`@Nullable`] annotation.
+It is also possible to specify optionality using xref:../rgant/rgant.adoc#_rgant_Nullable[`@Nullable`] annotation.
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Parameter_regexPattern.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Parameter_regexPattern.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Parameter_regexPattern.adoc
index bc29ef3..103ad2e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Parameter_regexPattern.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Parameter_regexPattern.adoc
@@ -8,7 +8,7 @@
 
 There are three attributes related to enforcing regular expressions:
 
-* The `regexPattern()` attribute validates the contents of any string parameter with respect to a regular expression pattern. It is ignored if applied to parameters of any other type. This attribute can also be specified for xref:rgant.adoc#_rgant-Property_regexPattern[properties].
+* The `regexPattern()` attribute validates the contents of any string parameter with respect to a regular expression pattern. It is ignored if applied to parameters of any other type. This attribute can also be specified for xref:../rgant/rgant.adoc#_rgant-Property_regexPattern[properties].
 
 * The `regexPatternFlags()` attribute specifies flags that modify the handling of the pattern.  The values are those
 that would normally be passed to `java.util.regex.Pattern#compile(String,int)`.

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PersistenceCapable.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PersistenceCapable.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PersistenceCapable.adoc
index 88d71c8..5e42bfa 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PersistenceCapable.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PersistenceCapable.adoc
@@ -22,12 +22,12 @@ This value is used internally to generate a string representation of an objects
 This can appear in several contexts, including:
 
 * as the value of `Bookmark#getObjectType()` and in the `toString()` value of `Bookmark`
- (see xref:rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`])
+ (see xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`])
  ** and thus in the "table-of-two-halves" pattern, as per (non-ASF) http://github.com/isisaddons/isis-module-poly[Isis addons' poly] module
-* in the serialization of `OidDto` in the xref:rgcms.adoc#_rgcms_schema-cmd[command] and xref:rgcms.adoc#_rgcms_schema-ixn[interaction] schemas
+* in the serialization of `OidDto` in the xref:../rgcms/rgcms.adoc#_rgcms_schema-cmd[command] and xref:../rgcms/rgcms.adoc#_rgcms_schema-ixn[interaction] schemas
 * in the URLs of the xref:ugvro.adoc#[RestfulObjects viewer]
 * in the URLs of the xref:ugvw.adoc#[Wicket viewer] (in general and in particular if xref:ugvw.adoc#_ugvw_features_hints-and-copy-url[copying URLs])
-* in XML snapshots generated by the xref:rgsvc.adoc#_rgsvc_api_XmlSnapshotService[`XmlSnapshotService`]
+* in XML snapshots generated by the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_XmlSnapshotService[`XmlSnapshotService`]
 
 
 The actual format of the object type used by Apache Isis for the concatenation of `schema()` and `@PersistenceCapable#table()`.
@@ -77,9 +77,9 @@ does _not_ correspond to an object type, because the `schema()` attribute is mis
 
 The rules of precedence for determining a domain object's object type are:
 
-1. xref:rgant.adoc#_rgant_Discriminator[`@Discriminator`]
+1. xref:../rgant/rgant.adoc#_rgant_Discriminator[`@Discriminator`]
 2. `@DomainObject#objectType`
-3. xref:rgant.adoc#_rgant_PersistenceCapable[`@PersistenceCapable`], if at least the `schema` attribute is defined.  +
+3. xref:../rgant/rgant.adoc#_rgant_PersistenceCapable[`@PersistenceCapable`], if at least the `schema` attribute is defined.  +
 +
 If both `schema` and `table` are defined, then the value is "`schema.table`".
 If only `schema` is defined, then the value is "`schema.className`".

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PostConstruct.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PostConstruct.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PostConstruct.adoc
index 1b1fff6..4af546d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PostConstruct.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PostConstruct.adoc
@@ -7,9 +7,9 @@
 
 The `@javax.annotation.PostConstruct` annotation, as defined in link:https://jcp.org/en/jsr/detail?id=250[JSR-250],  is recognized by Apache Isis as a callback method on domain services to be called just after they have been constructed, in order that they initialize themselves.
 
-It is also recognized for xref:ugbtb.adoc#_ugbtb_view-models[view models] (eg annotated with xref:rgant.adoc#_rgant-ViewModel[`@ViewModel`]).
+It is also recognized for xref:ugbtb.adoc#_ugbtb_view-models[view models] (eg annotated with xref:../rgant/rgant.adoc#_rgant-ViewModel[`@ViewModel`]).
 
-For the default application-scoped (singleton) domain services, this means that the method, if present, is called during the bootstrapping of the application.  For xref:rgant.adoc#_rgant-RequestScoped[`@RequestScoped`] domain services, the method is called at the beginning of the request.
+For the default application-scoped (singleton) domain services, this means that the method, if present, is called during the bootstrapping of the application.  For xref:../rgant/rgant.adoc#_rgant-RequestScoped[`@RequestScoped`] domain services, the method is called at the beginning of the request.
 
 The signature of the method is:
 
@@ -18,7 +18,7 @@ The signature of the method is:
 @PostConstruct                 <1>
 public void init() { ... }     <2>
 ----
-<1> It is not necessary to annotate the method with xref:rgant.adoc#_rgant-Programmatic[`@Programmatic`]; it will be automatically excluded from the Apache Isis metamodel.
+<1> It is not necessary to annotate the method with xref:../rgant/rgant.adoc#_rgant-Programmatic[`@Programmatic`]; it will be automatically excluded from the Apache Isis metamodel.
 <2> the method can have any name, but must have `public` visibility.
 
 In the form shown above the method accepts no arguments.  Alternatively - for domain services only, not view models - the method can accept a parameter of type `Map<String,String>`:
@@ -29,14 +29,14 @@ In the form shown above the method accepts no arguments.  Alternatively - for do
 @Programmatic
 public void init(Map<String,String> properties) { ... }
 ----
-Isis uses argument to pass in the configuration properties read from all xref:rgcfg.adoc#_rgcfg_configuration-files[configuration files]:
+Isis uses argument to pass in the configuration properties read from all xref:../rgcfg/rgcfg.adoc#_rgcfg_configuration-files[configuration files]:
 
 [TIP]
 ====
-Alternatively, you could inject xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`] into the service and read configuration properties using `DomainObjectContainer#getProperty(...)` and related methods.  Note that when using this latter API only those configuration properties prefixes `application.` key are provided.
+Alternatively, you could inject xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`] into the service and read configuration properties using `DomainObjectContainer#getProperty(...)` and related methods.  Note that when using this latter API only those configuration properties prefixes `application.` key are provided.
 ====
 
-A common use case is for domain services that interact with the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`].  For example:
+A common use case is for domain services that interact with the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`].  For example:
 
 [source,java]
 ----
@@ -58,7 +58,7 @@ public class MySubscribingService {
 
 [TIP]
 ====
-In this particular use case, it is generally simpler to just subclass from xref:rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[`AbstractSubscriber`].
+In this particular use case, it is generally simpler to just subclass from xref:../rgcms/rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[`AbstractSubscriber`].
 ====
 
 
@@ -68,4 +68,4 @@ Other use cases include obtaining connections to external datasources, eg subscr
 
 
 
-See also xref:rgant.adoc#_rgant-PreDestroy[`@PreDestroy`]
\ No newline at end of file
+See also xref:../rgant/rgant.adoc#_rgant-PreDestroy[`@PreDestroy`]
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PreDestroy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PreDestroy.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PreDestroy.adoc
index bf8a63b..13c6c0b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PreDestroy.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PreDestroy.adoc
@@ -9,7 +9,7 @@
 The `@javax.annotation.PreDestroy` annotation, as defined in link:https://jcp.org/en/jsr/detail?id=250[JSR-250], recognized by Apache Isis as a callback method on domain services to be called just as they go out of scope.
 
 
-For the default application-scoped (singleton) domain services, this means that the method, if present, is called just prior to the termination of the application.  For xref:rgant.adoc#_rgant-RequestScoped[`@RequestScoped`] domain services, the method is called at the end of the request.
+For the default application-scoped (singleton) domain services, this means that the method, if present, is called just prior to the termination of the application.  For xref:../rgant/rgant.adoc#_rgant-RequestScoped[`@RequestScoped`] domain services, the method is called at the end of the request.
 
 The signature of the method is:
 
@@ -18,10 +18,10 @@ The signature of the method is:
 @PreDestroy                         <1>
 public void deinit() { ... }    <2>
 ----
-<1> It is not necessary to annotate the method with xref:rgant.adoc#_rgant-Programmatic[`@Programmatic`]; it will be automatically excluded from the Apache Isis metamodel.
+<1> It is not necessary to annotate the method with xref:../rgant/rgant.adoc#_rgant-Programmatic[`@Programmatic`]; it will be automatically excluded from the Apache Isis metamodel.
 <2> the method can have any name, but must have `public` visibility, and accept no arguments.
 
-A common use case is for domain services that interact with the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`].  For example:
+A common use case is for domain services that interact with the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`].  For example:
 
 [source,java]
 ----
@@ -43,11 +43,11 @@ public class MySubscribingService {
 
 [TIP]
 ====
-In this particular use case, it is generally simpler to just subclass from xref:rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[`AbstractSubscriber`].
+In this particular use case, it is generally simpler to just subclass from xref:../rgcms/rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[`AbstractSubscriber`].
 ====
 
 Other use cases include obtaining connections to external datasources, eg subscribing to an ActiveMQ router, say, or initializing/cleaning up a background scheduler such as Quartz.
 
 
 
-See also xref:rgant.adoc#_rgant-PostConstruct[`@PostConstruct`]
\ No newline at end of file
+See also xref:../rgant/rgant.adoc#_rgant-PostConstruct[`@PostConstruct`]
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PrimaryKey.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PrimaryKey.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PrimaryKey.adoc
index b4b4164..4bbfbb9 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PrimaryKey.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PrimaryKey.adoc
@@ -8,7 +8,7 @@
 
 The `@javax.jdo.annotation.PrimaryKey` annotation is used by JDO/DataNucleus to indicate that a property is used as the primary key for an entity with application-managed identity.
 
-Apache Isis also uses this annotation in a very minimal way: to ensure that the framework's own logic to initialize newly instantiated objects (eg using xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer#newTransientInstance(...)`] does not touch the primary key, and also to ensure that the primary key property is always disabled (read-only).
+Apache Isis also uses this annotation in a very minimal way: to ensure that the framework's own logic to initialize newly instantiated objects (eg using xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer#newTransientInstance(...)`] does not touch the primary key, and also to ensure that the primary key property is always disabled (read-only).
 
 [NOTE]
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Programmatic.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Programmatic.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Programmatic.adoc
index 9a9a32e..cec0b6e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Programmatic.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Programmatic.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-The `@Programmatic` annotation causes the method to be excluded completely from the Apache Isis metamodel. This means it won't appear in any UI, and it won't appear in any xref:rgsvc.adoc#_rgsvc_api_MementoService[memento]s or xref:rgsvc.adoc#_rgsvc_api_XmlSnapshotService[snapshot]s.
+The `@Programmatic` annotation causes the method to be excluded completely from the Apache Isis metamodel. This means it won't appear in any UI, and it won't appear in any xref:../rgsvc/rgsvc.adoc#_rgsvc_api_MementoService[memento]s or xref:../rgsvc/rgsvc.adoc#_rgsvc_api_XmlSnapshotService[snapshot]s.
 
 A common use-case is to ignore implementation-level artifacts. For example:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property.adoc
index 0c867ef..3bcb1a1 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property.adoc
@@ -20,45 +20,45 @@ It is also possible to apply the annotation to actions of domain services that a
 | Description
 
 
-|xref:rgant.adoc#_rgant-Property_domainEvent[`domainEvent()`]
+|xref:../rgant/rgant.adoc#_rgant-Property_domainEvent[`domainEvent()`]
 |subtype of `PropertyDomainEvent` +
 (`PropertyDomainEvent.Default`)
-|the event type to be posted to the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] to broadcast the property's business rule checking (hide, disable, validate) and its modification (before and after).
+|the event type to be posted to the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] to broadcast the property's business rule checking (hide, disable, validate) and its modification (before and after).
 
 
-|xref:rgant.adoc#_rgant-Property_editing[`editing()`]
+|xref:../rgant/rgant.adoc#_rgant-Property_editing[`editing()`]
 |`ENABLED`, `DISABLED`, `AS_CONFIGURED` +
 (`AS_CONFIGURED`)
 |whether a property can be modified or cleared from within the UI
 
 
-|xref:rgant.adoc#_rgant-Property_fileAccept[`fileAccept()`]
+|xref:../rgant/rgant.adoc#_rgant-Property_fileAccept[`fileAccept()`]
 |Media type or file extension
-|Hints the files to be uploaded to a xref:rgcms.adoc#_rgcms_classes_value-types_Blob[`Blob`]
- or xref:rgcms.adoc#_rgcms_classes_value-types_Clob[`Clob`]. +
+|Hints the files to be uploaded to a xref:../rgcms/rgcms.adoc#_rgcms_classes_value-types_Blob[`Blob`]
+ or xref:../rgcms/rgcms.adoc#_rgcms_classes_value-types_Clob[`Clob`]. +
  +
 Note that this does not prevent the user from uploading some other file type; rather it merely defaults the file type in the file open dialog.
 
 
-|xref:rgant.adoc#_rgant-Property_hidden[`hidden()`]
+|xref:../rgant/rgant.adoc#_rgant-Property_hidden[`hidden()`]
 |`EVERYWHERE`, `OBJECT_FORMS`, `PARENTED_TABLES`, `STANDALONE_TABLES`, `ALL_TABLES`, `NOWHERE` +
 (`NOWHERE`)
 |indicates where (in the UI) the property should be hidden from the user.
 
 
-|xref:rgant.adoc#_rgant-Property_maxLength[`maxLength()`]
+|xref:../rgant/rgant.adoc#_rgant-Property_maxLength[`maxLength()`]
 |
 |maximum number of characters for string parameters; ignored otherwise +
 
-In many/most cases you should however use xref:rgant.adoc#_rgant-Column[`@Column#length()`]
+In many/most cases you should however use xref:../rgant/rgant.adoc#_rgant-Column[`@Column#length()`]
 
 
-|xref:rgant.adoc#_rgant-Property_mustSatisfy[`mustSatisfy()`]
+|xref:../rgant/rgant.adoc#_rgant-Property_mustSatisfy[`mustSatisfy()`]
 |implementation of `o.a.i.applib.spec.Specification`
 |allows arbitrary validation to be applied
 
 
-|xref:rgant.adoc#_rgant-Property_notPersisted[`notPersisted()`]
+|xref:../rgant/rgant.adoc#_rgant-Property_notPersisted[`notPersisted()`]
 |`true`, `false` +
 (`false`)
 |whether to exclude from snapshots. +
@@ -69,15 +69,15 @@ Property must also be annotated with `@javax.jdo.annotations.NotPersistent` in o
 ====
 
 
-|xref:rgant.adoc#_rgant-Property_optionality[`optionality()`]
+|xref:../rgant/rgant.adoc#_rgant-Property_optionality[`optionality()`]
 |
 |specifies a property is optional rather than mandatory +
 
-In many/most cases you should however use xref:rgant.adoc#_rgant-Column[`@Column#allowsNull()`]
+In many/most cases you should however use xref:../rgant/rgant.adoc#_rgant-Column[`@Column#allowsNull()`]
 
 
 
-|xref:rgant.adoc#_rgant-Property_regexPattern[`regexPattern()`]
+|xref:../rgant/rgant.adoc#_rgant-Property_regexPattern[`regexPattern()`]
 |regular expression
 |validates the contents of a string parameter against the regular expression pattern
 
@@ -124,7 +124,7 @@ public class Customer {
 
 [TIP]
 ====
-The annotation is one of a handful (others including xref:rgant.adoc#_rgant-Collection[`@Collection`], xref:rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`] and xref:rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`]) that can also be applied to the field, rather than the getter method.  This is specifically
+The annotation is one of a handful (others including xref:../rgant/rgant.adoc#_rgant-Collection[`@Collection`], xref:../rgant/rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`] and xref:../rgant/rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`]) that can also be applied to the field, rather than the getter method.  This is specifically
 so that boilerplate-busting tools such as link:https://projectlombok.org/[Project Lombok] can be used.
 ====
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout.adoc
index 1023ea9..96517ee 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout.adoc
@@ -19,40 +19,40 @@ The table below summarizes the annotation's attributes.
 | Description
 
 
-|xref:rgant.adoc#_rgant-PropertyLayout_cssClass[`cssClass()`]
+|xref:../rgant/rgant.adoc#_rgant-PropertyLayout_cssClass[`cssClass()`]
 |Any string valid as a CSS class
-|the css class that a property should have, to allow more targetted styling in xref:rgcfg.adoc#_rgcfg_application-specific_application-css[`application.css`]
+|the css class that a property should have, to allow more targetted styling in xref:../rgcfg/rgcfg.adoc#_rgcfg_application-specific_application-css[`application.css`]
 
 
-|xref:rgant.adoc#_rgant-PropertyLayout_describedAs[`describedAs()`]
+|xref:../rgant/rgant.adoc#_rgant-PropertyLayout_describedAs[`describedAs()`]
 |String
 |description of this property, eg to be rendered in a tooltip.
 
 
-|xref:rgant.adoc#_rgant-PropertyLayout_hidden[`hidden()`]
+|xref:../rgant/rgant.adoc#_rgant-PropertyLayout_hidden[`hidden()`]
 |`EVERYWHERE`, `OBJECT_FORMS`, `PARENTED_TABLES`, `STANDALONE_TABLES`, `ALL_TABLES`, `NOWHERE` +
 (`NOWHERE`)
 |indicates where (in the UI) the property should be hidden from the user.
 
 
-|xref:rgant.adoc#_rgant-PropertyLayout_labelPosition[`labelPosition()`]
+|xref:../rgant/rgant.adoc#_rgant-PropertyLayout_labelPosition[`labelPosition()`]
 |`LEFT`, `TOP`, `RIGHT`, `NONE` +
 (`LEFT`)
 |in forms, the positioning of the label relative to the property value. +
 
-Defaults is `LEFT`, unless xref:rgant.adoc#_rgant-PropertyLayout_multiLine[`multiLine`] in which case `TOP`.  The value `RIGHT` is only supported for boolean properties. +
+Defaults is `LEFT`, unless xref:../rgant/rgant.adoc#_rgant-PropertyLayout_multiLine[`multiLine`] in which case `TOP`.  The value `RIGHT` is only supported for boolean properties. +
 
-It is also possible to change the default through a xref:rgcfg.adoc#__rgcfg_configuring-core_isis-viewers-propertyLayout-labelPosition[configuration property]
+It is also possible to change the default through a xref:../rgcfg/rgcfg.adoc#__rgcfg_configuring-core_isis-viewers-propertyLayout-labelPosition[configuration property]
 
 
-|xref:rgant.adoc#_rgant-PropertyLayout_multiLine[`multiLine()`]
+|xref:../rgant/rgant.adoc#_rgant-PropertyLayout_multiLine[`multiLine()`]
 |Positive integer
 |for string properties, render as a text area over multiple lines.  +
 
-If set > 1, then xref:rgant.adoc#_rgant-PropertyLayout_labelPosition[`labelPosition`] defaults to TOP.
+If set > 1, then xref:../rgant/rgant.adoc#_rgant-PropertyLayout_labelPosition[`labelPosition`] defaults to TOP.
 
 
-|xref:rgant.adoc#_rgant-PropertyLayout_named[`named()`]
+|xref:../rgant/rgant.adoc#_rgant-PropertyLayout_named[`named()`]
 |String
 |to override the name inferred from the collection's name in code. +
 
@@ -65,13 +65,13 @@ A typical use case is if the desired name is a reserved Java keyword, such as `d
 |whether to HTML escape the name of this property.
 
 
-|xref:rgant.adoc#_rgant-PropertyLayout_renderedAsDayBefore[`renderedAsDayBefore()`]
+|xref:../rgant/rgant.adoc#_rgant-PropertyLayout_renderedAsDayBefore[`renderedAsDayBefore()`]
 |`true`, `false` +
 (`false`)
 |for date properties only, render the date as one day prior to the actually stored date.
 
 
-|xref:rgant.adoc#_rgant-PropertyLayout_typicalLength[`typicalLength()`]
+|xref:../rgant/rgant.adoc#_rgant-PropertyLayout_typicalLength[`typicalLength()`]
 |Positive integer.
 |the typical entry length of a field, use to determine the optimum width for display
 
@@ -113,7 +113,7 @@ As an alternative to using the `@PropertyLayout` annotation, a xref:ugvw.adoc#_u
 
 [TIP]
 ====
-The annotation is one of a handful (others including xref:rgant.adoc#_rgant-Collection[`@Collection`], xref:rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`] and xref:rgant.adoc#_rgant-Property[`@Property`]) that can also be applied to the field, rather than the getter method.  This is specifically
+The annotation is one of a handful (others including xref:../rgant/rgant.adoc#_rgant-Collection[`@Collection`], xref:../rgant/rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`] and xref:../rgant/rgant.adoc#_rgant-Property[`@Property`]) that can also be applied to the field, rather than the getter method.  This is specifically
 so that boilerplate-busting tools such as link:https://projectlombok.org/[Project Lombok] can be used.
 ====
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_cssClass.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_cssClass.adoc
index 4e51fef..c5580e8 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_cssClass.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_cssClass.adoc
@@ -5,9 +5,9 @@
 :_imagesdir: images/
 
 
-The `cssClass()` attribute can be used to render additional CSS classes in the HTML (a wrapping `<div>`) that represents the property.   xref:rgcfg.adoc#_rgcfg_application-specific_application-css[Application-specific CSS] can then be used to target and adjust the UI representation of that particular element.
+The `cssClass()` attribute can be used to render additional CSS classes in the HTML (a wrapping `<div>`) that represents the property.   xref:../rgcfg/rgcfg.adoc#_rgcfg_application-specific_application-css[Application-specific CSS] can then be used to target and adjust the UI representation of that particular element.
 
-This attribute can also be applied to xref:rgant.adoc#_rgant-DomainObjectLayout_cssClass[domain objects], xref:rgant.adoc#_rgant-ViewModelLayout_cssClass[view models], xref:rgant.adoc#_rgant-ActionLayout_cssClass[actions] xref:rgant.adoc#_rgant-CollectionLayout_cssClass[collections] and xref:rgant.adoc#_rgant-ParameterLayout_cssClass[parameters].
+This attribute can also be applied to xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_cssClass[domain objects], xref:../rgant/rgant.adoc#_rgant-ViewModelLayout_cssClass[view models], xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClass[actions] xref:../rgant/rgant.adoc#_rgant-CollectionLayout_cssClass[collections] and xref:../rgant/rgant.adoc#_rgant-ParameterLayout_cssClass[parameters].
 
 
 For example:

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_describedAs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_describedAs.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_describedAs.adoc
index d67555b..5644f47 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_describedAs.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_describedAs.adoc
@@ -6,7 +6,7 @@
 
 
 
-The `describedAs()` attribute is used to provide a short description of the property to the user.  In the xref:ugvw.adoc#[Wicket viewer] it is displayed as a 'tool tip'. The attribute can also be specified for xref:rgant.adoc#_rgant-CollectionLayout_describedAs[collections],  xref:rgant.adoc#_rgant-ActionLayout_describedAs[actions], xref:rgant.adoc#_rgant-ParameterLayout_describedAs[parameters], xref:rgant.adoc#_rgant-DomainObjectLayout_describedAs[domain objects] and xref:rgant.adoc#_rgant-ViewModelLayout_describedAs[view models].
+The `describedAs()` attribute is used to provide a short description of the property to the user.  In the xref:ugvw.adoc#[Wicket viewer] it is displayed as a 'tool tip'. The attribute can also be specified for xref:../rgant/rgant.adoc#_rgant-CollectionLayout_describedAs[collections],  xref:../rgant/rgant.adoc#_rgant-ActionLayout_describedAs[actions], xref:../rgant/rgant.adoc#_rgant-ParameterLayout_describedAs[parameters], xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_describedAs[domain objects] and xref:../rgant/rgant.adoc#_rgant-ViewModelLayout_describedAs[view models].
 
 For example:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_hidden.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_hidden.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_hidden.adoc
index 5c794d2..3391532 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_hidden.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_hidden.adoc
@@ -6,11 +6,11 @@
 
 
 
-The `hidden()` attribute indicates where (in the UI) the property should be hidden from the user.  This attribute can also be applied to xref:rgant.adoc#_rgant-Action_hidden[actions] and xref:rgant.adoc#_rgant-Collection_hidden[collections].
+The `hidden()` attribute indicates where (in the UI) the property should be hidden from the user.  This attribute can also be applied to xref:../rgant/rgant.adoc#_rgant-Action_hidden[actions] and xref:../rgant/rgant.adoc#_rgant-Collection_hidden[collections].
 
 [TIP]
 ====
-It is also possible to use xref:rgant.adoc#_rgant-PropertyLayout_hidden[`@PropertyLayout#hidden()`] or a xref:ugvw.adoc#_ugvw_layout_file-based[file-based layout] such that the property can be hidden at the view layer.
+It is also possible to use xref:../rgant/rgant.adoc#_rgant-PropertyLayout_hidden[`@PropertyLayout#hidden()`] or a xref:ugvw.adoc#_ugvw_layout_file-based[file-based layout] such that the property can be hidden at the view layer.
 Both options are provided with a view that in the future the view-layer semantics may be under the control of (expert) users, whereas domain-layer semantics should never be overridden or modified by the user.
 ====
 
@@ -58,7 +58,7 @@ The property should be hidden when displayed as a column of a table, either an o
 +
 The property should not be hidden, overriding any other metadata/conventions that would normally cause the property to be hidden. +
 
-For example, if a property is annotated with xref:rgant.adoc#_rgant-Title[`@Title`], then normally this should be hidden from all
+For example, if a property is annotated with xref:../rgant/rgant.adoc#_rgant-Title[`@Title`], then normally this should be hidden from all
 tables. Annotating with `@Property(where=Where.NOWHERE)` overrides this.
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_labelPosition.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_labelPosition.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_labelPosition.adoc
index 939ac6d..0b5a843 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_labelPosition.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_labelPosition.adoc
@@ -7,9 +7,9 @@
 
 
 
-The `labelPosition()` attribute determines the positioning of labels for properties.  This attribute can also be specified for xref:rgant.adoc#_rgant-ParameterLayout_labelPosition[parameters].
+The `labelPosition()` attribute determines the positioning of labels for properties.  This attribute can also be specified for xref:../rgant/rgant.adoc#_rgant-ParameterLayout_labelPosition[parameters].
 
-The positioning of labels is typically `LEFT`, but can be positioned to the `TOP`.  The one exception is xref:rgant.adoc#_rgant-ParameterLayout_multiLine[`multiLine()`] string properties, where the label defaults to `TOP` automatically (to provide as much real-estate for the multiline text field as possible).
+The positioning of labels is typically `LEFT`, but can be positioned to the `TOP`.  The one exception is xref:../rgant/rgant.adoc#_rgant-ParameterLayout_multiLine[`multiLine()`] string properties, where the label defaults to `TOP` automatically (to provide as much real-estate for the multiline text field as possible).
 
 For boolean properties a positioning of `RIGHT` is also allowed; this is ignored for all other types.
 
@@ -77,7 +77,7 @@ can be used instead, eg:
 ====
 If you want a consistent look-n-feel throughout the app, eg all property labels to the top, then it'd be rather frustrating to have to annotate every property.
 
-Instead, a default can be specified using a xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] in `isis.properties`:
+Instead, a default can be specified using a xref:../rgcfg/rgcfg.adoc#_rgcfg_configuring-core[configuration property] in `isis.properties`:
 
 [source,ini]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_multiLine.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_multiLine.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_multiLine.adoc
index 5400aa9..57da035 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_multiLine.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_multiLine.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-The `multiLine()` attribute specifies that the text field for a string property should span multiple lines.  It is ignored for other property types.  The attribute is also supported for xref:rgant.adoc#_rgant-ParameterLayout_multiLine[parameters].
+The `multiLine()` attribute specifies that the text field for a string property should span multiple lines.  It is ignored for other property types.  The attribute is also supported for xref:../rgant/rgant.adoc#_rgant-ParameterLayout_multiLine[parameters].
 
 For example:
 
@@ -40,5 +40,5 @@ can be used instead, eg:
 
 [NOTE]
 ====
-If set > 1 (as would normally be the case), then the default xref:rgant.adoc#_rgant-PropertyLayout_labelPosition[`labelPosition`] defaults to `TOP` (rather than `LEFT`, as would normally be the case).
+If set > 1 (as would normally be the case), then the default xref:../rgant/rgant.adoc#_rgant-PropertyLayout_labelPosition[`labelPosition`] defaults to `TOP` (rather than `LEFT`, as would normally be the case).
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_named.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_named.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_named.adoc
index a8516f7..5cef62f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_named.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_named.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-The `named()` attribute explicitly specifies the property's name, overriding the name that would normally be inferred from the Java source code.  This attribute can also be specified for xref:rgant.adoc#_rgant-ActionLayout_named[actions], xref:rgant.adoc#_rgant-CollectionLayout_named[collections], xref:rgant.adoc#_rgant-ParameterLayout_named[parameters], xref:rgant.adoc#_rgant-DomainObjectLayout_named[domain objects], xref:rgant.adoc#_rgant-ViewModelLayout_named[view models] and xref:rgant.adoc#_rgant-DomainServiceLayout_named[domain services].
+The `named()` attribute explicitly specifies the property's name, overriding the name that would normally be inferred from the Java source code.  This attribute can also be specified for xref:../rgant/rgant.adoc#_rgant-ActionLayout_named[actions], xref:../rgant/rgant.adoc#_rgant-CollectionLayout_named[collections], xref:../rgant/rgant.adoc#_rgant-ParameterLayout_named[parameters], xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_named[domain objects], xref:../rgant/rgant.adoc#_rgant-ViewModelLayout_named[view models] and xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_named[domain services].
 
 [TIP]
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_renderedAsDayBefore.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_renderedAsDayBefore.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_renderedAsDayBefore.adoc
index af517f2..f4451af 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_renderedAsDayBefore.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_renderedAsDayBefore.adoc
@@ -6,7 +6,7 @@
 
 
 
-The `renderedAsDayBefore()` attribute applies only to date properties whereby the date will be rendered as the day before the value actually held in the domain object.  It is ignored for properties of other types. This attribute is also supported for xref:rgant.adoc#_rgant-ParameterLayout_renderedAsDayBefore[parameters].
+The `renderedAsDayBefore()` attribute applies only to date properties whereby the date will be rendered as the day before the value actually held in the domain object.  It is ignored for properties of other types. This attribute is also supported for xref:../rgant/rgant.adoc#_rgant-ParameterLayout_renderedAsDayBefore[parameters].
 
 This behaviour might at first glance appear odd, but the rationale is to support the use case of a sequence of instances that represent adjacent intervals of time.  In such cases there would typically be `startDate` and `endDate` properties, eg for all of Q2.  Storing this as a half-closed interval -- eg `[1-Apr-2015, 1-July-2015)` -- can substantially simplify internal algorithms; the `endDate` of one interval will correspond to the `startDate` of the next.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_typicalLength.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_typicalLength.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_typicalLength.adoc
index 647957b..0d51135 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_typicalLength.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_typicalLength.adoc
@@ -6,7 +6,7 @@
 
 
 
-The `typicalLength()` attribute indicates the typical length of a string property.  It is ignored for properties of other types.  The attribute is also supported for xref:rgant.adoc#_rgant-ParameterLayout_typicalLength[parameters].
+The `typicalLength()` attribute indicates the typical length of a string property.  It is ignored for properties of other types.  The attribute is also supported for xref:../rgant/rgant.adoc#_rgant-ParameterLayout_typicalLength[parameters].
 
 The information is intended as a hint to the UI to determine the space that should be given to render a particular string property.  That said, note that the xref:ugvw.adoc#[Wicket viewer] uses the maximum space available for all fields, so in effect ignores this attribute.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_domainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_domainEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_domainEvent.adoc
index 9be1d74..75ca7fb 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_domainEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_domainEvent.adoc
@@ -13,7 +13,7 @@ Whenever a domain object (or list of domain objects) is to be rendered, the fram
 * pre-execute phase: before the modification of the property
 * post-execute: after the modification of the property
 
-Subscribers subscribe through the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] using either link:https://github.com/google/guava[Guava] or link:http://www.axonframework.org/[Axon Framework] annotations and can influence each of these phases.
+Subscribers subscribe through the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] using either link:https://github.com/google/guava[Guava] or link:http://www.axonframework.org/[Axon Framework] annotations and can influence each of these phases.
 
 By default the event raised is `PropertyDomainEvent.Default`. For example:
 
@@ -28,8 +28,8 @@ public class ToDoItem {
 
 The `domainEvent()` attribute allows a custom subclass to be emitted allowing more precise subscriptions (to those
 subclasses) to be defined instead.  This attribute is also supported for
- xref:rgant.adoc#_rgant-Action_domainEvent[actions] and
- xref:rgant.adoc#_rgant-Property_domainEvent[properties].
+ xref:../rgant/rgant.adoc#_rgant-Action_domainEvent[actions] and
+ xref:../rgant/rgant.adoc#_rgant-Property_domainEvent[properties].
 
 
 For example:
@@ -56,7 +56,7 @@ rather than through the constructor.  This substantially reduces the boilerplate
 
 == Subscribers
 
-Subscribers (which must be domain services) subscribe using either the link:https://github.com/google/guava[Guava] API or (if the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] has been appropriately configured) using the link:http://www.axonframework.org/[Axon Framework] API.  The examples below use the Guava API.
+Subscribers (which must be domain services) subscribe using either the link:https://github.com/google/guava[Guava] API or (if the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] has been appropriately configured) using the link:http://www.axonframework.org/[Axon Framework] API.  The examples below use the Guava API.
 
 Subscribers can be either coarse-grained (if they subscribe to the top-level event type):
 
@@ -150,5 +150,5 @@ then no event will be posted.
 == Raising events programmatically
 
 Normally events are only raised for interactions through the UI. However, events can be raised programmatically by
-wrapping the target object using the xref:rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`] service.
+wrapping the target object using the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`] service.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_editing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_editing.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_editing.adoc
index d914c48..2740d17 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_editing.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_editing.adoc
@@ -5,19 +5,19 @@
 :_imagesdir: images/
 
 
-The `editing()` attribute can be used to prevent a property from being modified or cleared, ie to make it read-only. This attribute can also be specified for xref:rgant.adoc#_rgant-Collection_editing[collections], and can also be specified for the xref:rgant.adoc#_rgant-DomainObject_editing[domain object].
+The `editing()` attribute can be used to prevent a property from being modified or cleared, ie to make it read-only. This attribute can also be specified for xref:../rgant/rgant.adoc#_rgant-Collection_editing[collections], and can also be specified for the xref:../rgant/rgant.adoc#_rgant-DomainObject_editing[domain object].
 
 The related `editingDisabledReason()` attribute specifies the a hard-coded reason why the property cannot be modified directly.
 
 Whether a property is enabled or disabled depends upon these factors:
 
-* whether the domain object has been configured as immutable through the xref:rgant.adoc#_rgant-DomainObject_editing[`@DomainObject#editing()`] attribute
+* whether the domain object has been configured as immutable through the xref:../rgant/rgant.adoc#_rgant-DomainObject_editing[`@DomainObject#editing()`] attribute
 
-* else (that is, if the domain object's editability is specified as being `AS_CONFIGURED`), then the value of the xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.objects.editing`.  If set to `false`, then the object's properties (and collections) are _not_ editable
+* else (that is, if the domain object's editability is specified as being `AS_CONFIGURED`), then the value of the xref:../rgcfg/rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.objects.editing`.  If set to `false`, then the object's properties (and collections) are _not_ editable
 
 * else, then the value of the `@Property(editing=...)` attribute itself
 
-* else, the result of invoking any supporting xref:rgcms.adoc#_rgcms_methods_prefixes_disable[`disable...()`] supporting methods
+* else, the result of invoking any supporting xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_disable[`disable...()`] supporting methods
 
 
 Thus, to make a property read-only even if the object would otherwise be editable, use:

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_fileAccept.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_fileAccept.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_fileAccept.adoc
index d73e923..2d45412 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_fileAccept.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_fileAccept.adoc
@@ -6,9 +6,9 @@
 
 
 
-The `fileAccept()` attribute applies only to xref:rgcms.adoc#_rgcms_classes_value-types_Blob[`Blob`]
-or xref:rgcms.adoc#_rgcms_classes_value-types_Clob[`Clob`] parameters, indicating the type of file to accept when
-uploading a new value.   The attribute is also supported on xref:rgant.adoc#_rgant-Parameter_fileAccept[parameters].
+The `fileAccept()` attribute applies only to xref:../rgcms/rgcms.adoc#_rgcms_classes_value-types_Blob[`Blob`]
+or xref:../rgcms/rgcms.adoc#_rgcms_classes_value-types_Clob[`Clob`] parameters, indicating the type of file to accept when
+uploading a new value.   The attribute is also supported on xref:../rgant/rgant.adoc#_rgant-Parameter_fileAccept[parameters].
 
 
 For example:

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_hidden.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_hidden.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_hidden.adoc
index 4384bc2..71a7461 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_hidden.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_hidden.adoc
@@ -6,11 +6,11 @@
 
 
 
-Properties can be hidden at the domain-level, indicating that they are not visible to the end-user.  This attribute can also be applied to xref:rgant.adoc#_rgant-ActionLayout_hidden[actions] and xref:rgant.adoc#_rgant-CollectionLayout_hidden[collections].
+Properties can be hidden at the domain-level, indicating that they are not visible to the end-user.  This attribute can also be applied to xref:../rgant/rgant.adoc#_rgant-ActionLayout_hidden[actions] and xref:../rgant/rgant.adoc#_rgant-CollectionLayout_hidden[collections].
 
 [TIP]
 ====
-It is also possible to use xref:rgant.adoc#_rgant-Property_hidden[`@Property#hidden()`] to hide an action at the domain layer.  Both options are provided with a view that in the future the view-layer semantics may be under the control of (expert) users, whereas domain-layer semantics should never be overridden or modified by the user.
+It is also possible to use xref:../rgant/rgant.adoc#_rgant-Property_hidden[`@Property#hidden()`] to hide an action at the domain layer.  Both options are provided with a view that in the future the view-layer semantics may be under the control of (expert) users, whereas domain-layer semantics should never be overridden or modified by the user.
 ====
 
 For example:
@@ -56,7 +56,7 @@ The property should be hidden when displayed as a column of a table, either an o
 +
 The property should not be hidden, overriding any other metadata/conventions that would normally cause the property to be hidden. +
 
-For example, if a property is annotated with xref:rgant.adoc#_rgant-Title[`@Title`], then normally this should be hidden from all
+For example, if a property is annotated with xref:../rgant/rgant.adoc#_rgant-Title[`@Title`], then normally this should be hidden from all
 tables. Annotating with `@Property(where=Where.NOWHERE)` overrides this.
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_maxLength.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_maxLength.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_maxLength.adoc
index 37b93ec..1cfceae 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_maxLength.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_maxLength.adoc
@@ -6,10 +6,10 @@
 
 
 
-The `maxLength()` attribute applies only to `String` properties, indicating the maximum number of characters that the user may enter (for example in a text field in the UI).  The attribute It is ignored if applied to properties of any other type.  This attribute can also be applied to xref:rgant.adoc#_rgant-Parameter_maxLength[parameters].
+The `maxLength()` attribute applies only to `String` properties, indicating the maximum number of characters that the user may enter (for example in a text field in the UI).  The attribute It is ignored if applied to properties of any other type.  This attribute can also be applied to xref:../rgant/rgant.adoc#_rgant-Parameter_maxLength[parameters].
 
 
-That said, properties are most commonly defined on persistent domain objects (entities), in which case the JDO xref:rgant.adoc#_rgant-Column[`@Column`] will in any case need to be specified.  Apache Isis can infer the `maxLength` semantic directly from the equivalent `@Column#length()` annotation/attribute.
+That said, properties are most commonly defined on persistent domain objects (entities), in which case the JDO xref:../rgant/rgant.adoc#_rgant-Column[`@Column`] will in any case need to be specified.  Apache Isis can infer the `maxLength` semantic directly from the equivalent `@Column#length()` annotation/attribute.
 
 For example:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_mustSatisfy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_mustSatisfy.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_mustSatisfy.adoc
index e88ca71..6ac65b6 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_mustSatisfy.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_mustSatisfy.adoc
@@ -8,11 +8,11 @@
 
 
 The `mustSatisfy()` attribute allows arbitrary validation to be applied to properties using an (implementation of a) `org.apache.isis.applib.spec.Specification` object.
- The attribute is also supported on xref:rgant.adoc#_rgant-Parameter_mustSatisfy[parameters].
+ The attribute is also supported on xref:../rgant/rgant.adoc#_rgant-Parameter_mustSatisfy[parameters].
 
 [TIP]
 ====
-The specification implementations can (of course) be reused between properties and xref:rgant.adoc#_rgant-Parameter_mustSatisfy[parameters].
+The specification implementations can (of course) be reused between properties and xref:../rgant/rgant.adoc#_rgant-Parameter_mustSatisfy[parameters].
 ====
 
 The `Specification` is consulted during validation, being passed the proposed value.  If the proposed value fails, then the value returned is the used as the invalidity reason.

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_notPersisted.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_notPersisted.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_notPersisted.adoc
index 7bde4bf..b47eb39 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_notPersisted.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_notPersisted.adoc
@@ -7,7 +7,7 @@
 
 
 
-The (somewhat misnamed) `notPersisted()` attribute indicates that the collection should be excluded from any snapshots generated by the xref:rgsvc.adoc#_rgsvc_api_XmlSnapshotService[`XmlSnapshotService`].  This attribute is also supported for xref:rgant.adoc#_rgant-Collection_notPersisted[collections].
+The (somewhat misnamed) `notPersisted()` attribute indicates that the collection should be excluded from any snapshots generated by the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_XmlSnapshotService[`XmlSnapshotService`].  This attribute is also supported for xref:../rgant/rgant.adoc#_rgant-Collection_notPersisted[collections].
 
 
 [WARNING]

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_optionality.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_optionality.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_optionality.adoc
index 1713bb4..a01c409 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_optionality.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_optionality.adoc
@@ -8,11 +8,11 @@
 
 
 
-By default, Apache Isis assumes that all properties of an domain object or view model are required (mandatory).  The `optionality()` attribute allows this to be relaxed.  The attribute is also supported for xref:rgant.adoc#_rgant-Parameter_optionality[parameters].
+By default, Apache Isis assumes that all properties of an domain object or view model are required (mandatory).  The `optionality()` attribute allows this to be relaxed.  The attribute is also supported for xref:../rgant/rgant.adoc#_rgant-Parameter_optionality[parameters].
 
-That said, properties are most commonly defined on persistent domain objects (entities), in which case the JDO xref:rgant.adoc#_rgant-Column[`@Column`] should be specified. Apache Isis can infer the maxLength directly from the equivalent @Column#length() annotation.
+That said, properties are most commonly defined on persistent domain objects (entities), in which case the JDO xref:../rgant/rgant.adoc#_rgant-Column[`@Column`] should be specified. Apache Isis can infer the maxLength directly from the equivalent @Column#length() annotation.
 
-That said, properties are most commonly defined on persistent domain objects (entities), in which case the JDO xref:rgant.adoc#_rgant-Column[`@Column`] will in any case need to be specified.  Apache Isis can infer the `optionality` semantic directly from the equivalent `@Column#allowsNull()` annotation/attribute.
+That said, properties are most commonly defined on persistent domain objects (entities), in which case the JDO xref:../rgant/rgant.adoc#_rgant-Column[`@Column`] will in any case need to be specified.  Apache Isis can infer the `optionality` semantic directly from the equivalent `@Column#allowsNull()` annotation/attribute.
 
 For example:
 
@@ -129,6 +129,6 @@ public class Customer {
 
 [NOTE]
 ====
-It is also possible to specify optionality using xref:rgant.adoc#_rgant_Nullable[`@Nullable`] annotation.
+It is also possible to specify optionality using xref:../rgant/rgant.adoc#_rgant_Nullable[`@Nullable`] annotation.
 ====
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_publishing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_publishing.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_publishing.adoc
index db0ae15..1ccb708 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_publishing.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_publishing.adoc
@@ -8,15 +8,15 @@
 
 
 The `publishing()` attribute determines whether and how a property edit is published via the registered implementation
-of a xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`]) or
-xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`].  This attribute is also supported
-for xref:rgant.adoc#_rgant-DomainObject_publishing[domain objects], where it controls whether changed objects are
-published as events, and for xref:rgant.adoc#_rgant_Property_publishing[`@Property#publishing()`], where it controls
+of a xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`]) or
+xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`].  This attribute is also supported
+for xref:../rgant/rgant.adoc#_rgant-DomainObject_publishing[domain objects], where it controls whether changed objects are
+published as events, and for xref:../rgant/rgant.adoc#_rgant_Property_publishing[`@Property#publishing()`], where it controls
 whether property edits are published as events.
 
 A common use case is to notify external "downstream" systems of changes in the state of the Isis application.
 The default value for the attribute is `AS_CONFIGURED`, meaning that the
-xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.services.publish.properties` is used to
+xref:../rgcfg/rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.services.publish.properties` is used to
 determine the whether the property is published:
 
 * `all` +

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_regexPattern.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_regexPattern.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_regexPattern.adoc
index 279cdce..bad33cc 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_regexPattern.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_regexPattern.adoc
@@ -8,7 +8,7 @@
 
 There are three attributes related to enforcing regular expressions:
 
-* The `regexPattern()` attribute validates the contents of any string property with respect to a regular expression pattern. It is ignored if applied to properties of any other type. This attribute can also be specified for xref:rgant.adoc#_rgant-Parameter_regexPattern[parameters].
+* The `regexPattern()` attribute validates the contents of any string property with respect to a regular expression pattern. It is ignored if applied to properties of any other type. This attribute can also be specified for xref:../rgant/rgant.adoc#_rgant-Parameter_regexPattern[parameters].
 
 * The `regexPatternFlags()` attribute specifies flags that modify the handling of the pattern.  The values are those
 that would normally be passed to `java.util.regex.Pattern#compile(String,int)`.

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-RequestScoped.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-RequestScoped.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-RequestScoped.adoc
index 7372d56..11c8fe1 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-RequestScoped.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-RequestScoped.adoc
@@ -7,11 +7,11 @@
 
 
 
-The `@javax.enterprise.context.RequestScoped` link:https://jcp.org/en/jsr/detail?id=299[JSR-299] CDI annotation is used to specify that a xref:rgant.adoc#_rgant-DomainService[domain service] should be request-scoped rather than a singleton.
+The `@javax.enterprise.context.RequestScoped` link:https://jcp.org/en/jsr/detail?id=299[JSR-299] CDI annotation is used to specify that a xref:../rgant/rgant.adoc#_rgant-DomainService[domain service] should be request-scoped rather than a singleton.
 
 Although Apache Isis does not (currently) leverage CDI, the semantics are the same as request-scoped service; a new instance is created for each HTTP request, reserved for the exclusive use of all objects interacted with during that request.
 
-One of the built-in domain services that uses this annotation is xref:rgsvc.adoc#_rgsvc_api_Scratchpad[`Scratchpad`], intended to allow the arbitrary sharing of data between objects.  Here is the full source code of this service is:
+One of the built-in domain services that uses this annotation is xref:../rgsvc/rgsvc.adoc#_rgsvc_api_Scratchpad[`Scratchpad`], intended to allow the arbitrary sharing of data between objects.  Here is the full source code of this service is:
 
 
 [source,java]

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Title.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Title.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Title.adoc
index 0b92462..0abf793 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Title.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Title.adoc
@@ -40,7 +40,7 @@ present in the title column. This convention can be overridden using
 
 == Lombok support
 
-If xref:dg.adoc#_dg_ide_project-lombok[Project Lombok] is being used, then `@Title` can be specified on the backing field.
+If xref:../dg/dg.adoc#_dg_ide_project-lombok[Project Lombok] is being used, then `@Title` can be specified on the backing field.
 
 For example:
 

[28/58] [abbrv] isis git commit: ISIS-1521: fixes further xref links between guides

[da...@apache.org]

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_eagerly-registering-entities.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_eagerly-registering-entities.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_eagerly-registering-entities.adoc
index c947ae6..3865041 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_eagerly-registering-entities.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_eagerly-registering-entities.adoc
@@ -18,6 +18,6 @@ The framework thus provide mechanisms to search for all `@PersistenceCapable` en
 
 * for earlier versions the `isis.persistor.datanucleus.RegisterEntities.packagePrefix` configuration property can be specified.  To bootstrap as a webapp this is usually specified in `persistor_datanucleus.properties`.  (This is also supported in 1.9.0 if no `AppManifest` is specified.  For integration testing this can be specified programatically.
 
-Further discussion on specifying the package(s) in integration testing (for either approach) can be found in the xref:ugtst.adoc#_ugtst_integ-test-support_bootstrapping[user guide].
+Further discussion on specifying the package(s) in integration testing (for either approach) can be found in the xref:../ugtst/ugtst.adoc#_ugtst_integ-test-support_bootstrapping[user guide].
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_properties.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_properties.adoc
index ff1be04..8e5c83e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_properties.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_properties.adoc
@@ -28,7 +28,7 @@ These configuration properties are typically stored in `WEB-INF/persistor_datanu
 |`isis.persistor.datanucleus.` +
 `RegisterEntities.packagePrefix`
 |fully qualified package names (CSV)
-|that specifies the entities early rather than allow DataNucleus to find the entities lazily.  Further xref:ugodn.adoc#_ugodn_configuring_eagerly-registering-entities[discussion below].
+|that specifies the entities early rather than allow DataNucleus to find the entities lazily.  Further xref:../ugodn/ugodn.adoc#_ugodn_configuring_eagerly-registering-entities[discussion below].
 
 This property is IGNORED if the xref:../rgcfg/rgcfg.adoc#_rgcfg_configuring-components[`isis.appManifest`] configuration property is specified, or if an xref:../rgcms/rgcms.adoc#_rgcms_classes_super_AppManifest[`AppManifest`] is provided programmatically.
 
@@ -60,7 +60,7 @@ This property is IGNORED if the xref:../rgcfg/rgcfg.adoc#_rgcfg_configuring-comp
 `datanucleus.persistenceByReachabilityAtCommit`
 |`false`
 |We recommend this setting is disabled.  +
-Further xref:ugodn.adoc#_ugodn_configuring_disabling-persistence-by-reachability[discussion below].
+Further xref:../ugodn/ugodn.adoc#_ugodn_configuring_disabling-persistence-by-reachability[discussion below].
 
 |===
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_configuring-isis-to-use-shiro.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_configuring-isis-to-use-shiro.adoc b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_configuring-isis-to-use-shiro.adoc
index 62645cd..f1aa95d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_configuring-isis-to-use-shiro.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_configuring-isis-to-use-shiro.adoc
@@ -38,7 +38,7 @@ be configured in `authentication_shiro.properties` file:
 isis.authentication.shiro.autoLogoutIfAlreadyAuthenticated=false
 ----
 
-This configuration property only comes into effect for the xref:ugvro.adoc#[Restful Objects viewer]; if set then
+This configuration property only comes into effect for the xref:../ugvro/ugvro.adoc#[Restful Objects viewer]; if set then
 the Shiro subject - if found to be still authenticated - will be logged out anyway and then re-authenticated.
 
 [WARNING]

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-ini-realm.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-ini-realm.adoc b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-ini-realm.adoc
index 306ecb3..3e3ce94 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-ini-realm.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-ini-realm.adoc
@@ -105,7 +105,7 @@ com.mycompany.myapp                          # ditto
 
 [TIP]
 ====
-The format of the permissions string is configurable in Shiro, and Apache Isis uses this to provide an extended wildcard format, described xref:ugsec.adoc#_ugsec_shiro-isis-enhanced-wildcard-permission[here].
+The format of the permissions string is configurable in Shiro, and Apache Isis uses this to provide an extended wildcard format, described xref:../ugsec/ugsec.adoc#_ugsec_shiro-isis-enhanced-wildcard-permission[here].
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-isis-enhanced-wildcard-permission.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-isis-enhanced-wildcard-permission.adoc b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-isis-enhanced-wildcard-permission.adoc
index 35ae045..241a297 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-isis-enhanced-wildcard-permission.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-isis-enhanced-wildcard-permission.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-If using the text-based xref:ugsec.adoc#_ugsec_shiro-ini-realm[`IniRealm`] or xref:ugsec.adoc#_ugsec_shiro-isis-ldap-realm[Isis' LDAP realm], then note that Shiro also allows the string representation of the permissions to be mapped (resolved) to alternative `Permission` instances.  Apache Isis provides its own `IsisPermission` which introduces the concept of a "veto".
+If using the text-based xref:../ugsec/ugsec.adoc#_ugsec_shiro-ini-realm[`IniRealm`] or xref:../ugsec/ugsec.adoc#_ugsec_shiro-isis-ldap-realm[Isis' LDAP realm], then note that Shiro also allows the string representation of the permissions to be mapped (resolved) to alternative `Permission` instances.  Apache Isis provides its own `IsisPermission` which introduces the concept of a "veto".
 
 A vetoing permission is one that prevents access to a feature, rather than grants it.  This is useful in some situations where most users have access to most features, and only a small number of features are particularly sensitive.  The configuration can therefore be set up to grant fairly broad-brush permissions and then veto permission for the sensitive features for those users that do not have access.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_usage-by-isis-viewers.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_usage-by-isis-viewers.adoc b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_usage-by-isis-viewers.adoc
index 06c3dab..f6a8fa4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_usage-by-isis-viewers.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_usage-by-isis-viewers.adoc
@@ -6,7 +6,7 @@
 
 
 
-By and large the security mechanisms within Isis are transparent to the rest of the framework (the xref:ugvw.adoc#[Wicket Viewer] and xref:ugvro.adoc#[Restful Objects viewer], and the overall xref:../rgcfg/rgcfg.adoc#_rgcfg[runtime]).
+By and large the security mechanisms within Isis are transparent to the rest of the framework (the xref:../ugvw/ugvw.adoc#[Wicket Viewer] and xref:../ugvro/ugvro.adoc#[Restful Objects viewer], and the overall xref:../rgcfg/rgcfg.adoc#_rgcfg[runtime]).
 
 That said, it is the responsibility of the viewers to ensure that there is a viewers to ensure that for each request there is a valid user session present.  The sections below explain how this works.
 
@@ -15,7 +15,7 @@ That said, it is the responsibility of the viewers to ensure that there is a vie
 
 == Wicket Viewer
 
-The xref:ugvw.adoc#[Wicket viewer] defines a relatively small number of pages (by which we mean subclasses of link:http://ci.apache.org/projects/wicket/apidocs/6.0.x/org/apache/wicket/markup/html/WebPage.html[`org.apache.wicket.markup.html.WebPage`]):
+The xref:../ugvw/ugvw.adoc#[Wicket viewer] defines a relatively small number of pages (by which we mean subclasses of link:http://ci.apache.org/projects/wicket/apidocs/6.0.x/org/apache/wicket/markup/html/WebPage.html[`org.apache.wicket.markup.html.WebPage`]):
 
 * about page
 * action prompt page
@@ -37,7 +37,7 @@ which means that they can only be accessed by a user with an authenticated sessi
 
 [TIP]
 ====
-The sign-in page to render is pluggable; see xref:ugvw.adoc#_ugvw_extending_custom-pages[extensions chapter] for details.
+The sign-in page to render is pluggable; see xref:../ugvw/ugvw.adoc#_ugvw_extending_custom-pages[extensions chapter] for details.
 ====
 
 In the sign-in page the viewer calls to the Isis Authenticator API, and obtains back a user/role.  It also adds in its special reserved role (per the annotation above) and then continues on to whichever page the user was attempting to access (usually the home page).
@@ -49,11 +49,11 @@ Similarly, for those object members that _are_ visible, the viewer also checks i
 
 === User-registration
 
-As well as providing a sign-in screen, the Wicket viewer also provides the ability for xref:_user_registration[users to self-register].  By and large this operates outside of Apache Isis' security mechanisms; indeed the various pages (sign-up, sign-up verification, password reset) are all rendered _without_ there being any current user session.  These pages all "reach inside" Apache Isis framework using a mechanism similar to xref:ugbtb.adoc#_ugbtb_headless-access[Headless access] in order to actually do their stuff.
+As well as providing a sign-in screen, the Wicket viewer also provides the ability for xref:_user_registration[users to self-register].  By and large this operates outside of Apache Isis' security mechanisms; indeed the various pages (sign-up, sign-up verification, password reset) are all rendered _without_ there being any current user session.  These pages all "reach inside" Apache Isis framework using a mechanism similar to xref:../ugbtb/ugbtb.adoc#_ugbtb_headless-access[Headless access] in order to actually do their stuff.
 
 [TIP]
 ====
-The sign-in verification page to render is pluggable; see xref:ugvw.adoc#_ugvw_extending_custom-pages[extensions chapter] for details.
+The sign-in verification page to render is pluggable; see xref:../ugvw/ugvw.adoc#_ugvw_extending_custom-pages[extensions chapter] for details.
 ====
 
 User registration is only available if the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UserRegistrationService[`UserRegistrationService`] is configured; this is used by the framework to actually create new instances of the user as accessed by the corresponding (Shiro) realm.
@@ -66,7 +66,7 @@ If you are using an LDAP realm and want to enable user-self registration then yo
 
 == Restful Objects Viewer
 
-Unlike the Wicket viewer, the xref:ugvro.adoc#[Restful Objects viewer] does *not* provide any sort of login page; rather it provides a pluggable authentication strategy, delegated to by the `IsisSessionFilter` filter defined in `web.xml`.  The authentication strategy is responsible for ensuring that a session is available for the REST resource.
+Unlike the Wicket viewer, the xref:../ugvro/ugvro.adoc#[Restful Objects viewer] does *not* provide any sort of login page; rather it provides a pluggable authentication strategy, delegated to by the `IsisSessionFilter` filter defined in `web.xml`.  The authentication strategy is responsible for ensuring that a session is available for the REST resource.
 
 The API of `AuthenticationSessionStrategy` is simply:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_bdd-spec-support_key-classes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_bdd-spec-support_key-classes.adoc b/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_bdd-spec-support_key-classes.adoc
index b6fdf5e..fba3f67 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_bdd-spec-support_key-classes.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_bdd-spec-support_key-classes.adoc
@@ -9,7 +9,7 @@
 
 There are some key framework classes that make up the spec support; these are discussed below.
 
-NOTE: some of these are also used by Apache Isis' xref:ugtst.adoc#_ugtst_integ-test-support[Integration Test support].
+NOTE: some of these are also used by Apache Isis' xref:../ugtst/ugtst.adoc#_ugtst_integ-test-support[Integration Test support].
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_bdd-spec-support_writing-a-bdd-spec.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_bdd-spec-support_writing-a-bdd-spec.adoc b/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_bdd-spec-support_writing-a-bdd-spec.adoc
index cc5246d..d4a7be0 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_bdd-spec-support_writing-a-bdd-spec.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_bdd-spec-support_writing-a-bdd-spec.adoc
@@ -21,7 +21,7 @@ For example, given a feature that involves `Customer` and `Order`, have the step
 +
 The `glue` attribute of the Cucumber-JVM JUnit runner eallows you to indicate which package(s) should be recursively searched to find any glue.
 
-* a system initializer class.  You can reuse the  system initializer from any integration tests (as described in xref:ugtst.adoc#_ugtst_integ-test-support[Integration Test Support], bootstrapping section).
+* a system initializer class.  You can reuse the  system initializer from any integration tests (as described in xref:../ugtst/ugtst.adoc#_ugtst_integ-test-support[Integration Test Support], bootstrapping section).
 
 
 Here's an example of a feature from the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]:

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_fixture-scripts_api-and-usage.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_fixture-scripts_api-and-usage.adoc b/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_fixture-scripts_api-and-usage.adoc
index b94a39a..d7a21d2 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_fixture-scripts_api-and-usage.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_fixture-scripts_api-and-usage.adoc
@@ -42,7 +42,7 @@ public class DomainAppFixturesProvider implements FixtureScriptsSpecificationPro
 }
 ----
 <1> search for all fixture scripts under the package containing this class
-<2> if the same fixture script (class) is encountered more than once, then run anyway; more on this in xref:ugtst.adoc#__ugtst_fixture-scripts_api-and-usage_organizing[Organizing Fixture scripts]], below.
+<2> if the same fixture script (class) is encountered more than once, then run anyway; more on this in xref:../ugtst/ugtst.adoc#__ugtst_fixture-scripts_api-and-usage_organizing[Organizing Fixture scripts]], below.
 <3> specify the fixture script class to provide as the default for the service's "run fixture script" action
 <4> whether the service's "run fixture script" action should display other fixture scripts using a choices drop down or (if there are very many of them) using an auto-complete
 <5> if present, enables a "recreate objects and return first" action to be displayed in the UI
@@ -80,7 +80,7 @@ public class DomainAppFixturesService extends FixtureScripts {     // <3>
 <2> ... under the "Prototyping" menu
 <3> inherit from `org.apache.isis.applib.fixturescripts.FixtureScripts`
 <4> search for all fixture scripts under the "domainapp" package; in your code this would probably be "com.mycompany.myapp" or similar
-<5> if the same fixture script (class) is encountered more than once, then run anyway; more on this in xref:ugtst.adoc#__ugtst_fixture-scripts_api-and-usage_organizing[Organizing Fixture scripts]], below.
+<5> if the same fixture script (class) is encountered more than once, then run anyway; more on this in xref:../ugtst/ugtst.adoc#__ugtst_fixture-scripts_api-and-usage_organizing[Organizing Fixture scripts]], below.
 <6> (optional) specify a default fixture script to run, in this case `RecreateSimpleObjects` fixture script (see below)
 <7> make all fixture scripts found available as a drop-down (by increasing the visibility of this method to `public`)
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_integ-test-support_bootstrapping.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_integ-test-support_bootstrapping.adoc b/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_integ-test-support_bootstrapping.adoc
index 8ce55e3..d9b3939 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_integ-test-support_bootstrapping.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_integ-test-support_bootstrapping.adoc
@@ -259,7 +259,7 @@ public abstract class DomainAppIntegTest {
 ----
 <1> ensure that logging messages don't get swallowed
 <2> initialize the Apache Isis runtime
-<3> primarily exists to support the writing of xref:ugtst.adoc#_ugtst_bdd-spec-support[BDD specifications], but also enables finer-grained management of sessions/transactions (discussed below).
+<3> primarily exists to support the writing of xref:../ugtst/ugtst.adoc#_ugtst_bdd-spec-support[BDD specifications], but also enables finer-grained management of sessions/transactions (discussed below).
 
 
 [[__ugtst_integ-test-support_bootstrapping_IntegrationTestAbstract]]
@@ -292,9 +292,9 @@ Although not mandatory, this provides a number of helper/convenience methods and
         ExceptionRecognizerTranslate.create();
 ----
 <1> ensures an Apache Isis session/transaction running for each test
-<2> sets up a JMock context (using Apache Isis' extension to JMock as described in xref:ugtst.adoc#_ugtst_unit-test-support_jmock-extensions[JMock Extensions].
+<2> sets up a JMock context (using Apache Isis' extension to JMock as described in xref:../ugtst/ugtst.adoc#_ugtst_unit-test-support_jmock-extensions[JMock Extensions].
 <3> standard JUnit rule for writing tests that throw exceptions
-<4> to capture messages that require translation, as described in xref:ugbtb.adoc#_ugbtb_i18n[i18 support].
+<4> to capture messages that require translation, as described in xref:../ugbtb/ugbtb.adoc#_ugbtb_i18n[i18 support].
 
 All of these rules could be inlined in your own base class; as we say, they are a convenience.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_integ-test-support_wrapper-factory.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_integ-test-support_wrapper-factory.adoc b/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_integ-test-support_wrapper-factory.adoc
index cfaa0be..6cd7ec7 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_integ-test-support_wrapper-factory.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_integ-test-support_wrapper-factory.adoc
@@ -86,7 +86,7 @@ If there is a supporting `addTo...()` or `removeFrom...()` method, then these ca
 +
 [NOTE]
 ====
-In this respect the wrapper is more functional than the xref:ugvw.adoc#[Wicket viewer] (which does not expose the ability to mutate collections directly).
+In this respect the wrapper is more functional than the xref:../ugvw/ugvw.adoc#[Wicket viewer] (which does not expose the ability to mutate collections directly).
 ====
 
 * for *_object actions_* the test can call the action method itself.

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_architecture.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_architecture.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_architecture.adoc
index 24c3228..5f089e7 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_architecture.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_architecture.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-The xref:ugvro.adoc#[RestfulObjects viewer] implements the http://restfulobjects.org[Restful Object spec], meaning
+The xref:../ugvro/ugvro.adoc#[RestfulObjects viewer] implements the http://restfulobjects.org[Restful Object spec], meaning
 that it defines a well-defined set of endpoint URLs as resources, and generates a well-defined set of (JSON)
 representations when these resources are accessed.
 
@@ -33,7 +33,7 @@ xref:../rgfis/rgfis.adoc#_rgfis_spi_ContentNegotiationService[`ContentNegotiatio
 HTTP `Accept` header.  If the implementation does not recognize the value of the header, if can simply return `null`. +
 +
 The framework provides a number of implementations; an implementation that handles the
-xref:ugvro.adoc#_ugvro_simplified-representations[simplified representation] of the Apache Isis profile; an implementation that provides support for the `x-ro-domain-type` parameter, and a
+xref:../ugvro/ugvro.adoc#_ugvro_simplified-representations[simplified representation] of the Apache Isis profile; an implementation that provides support for the `x-ro-domain-type` parameter, and a
 default/fallback implementation that returns the representations defined by the RO spec.
 
 * `ContentMappingService` +

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_configuration-properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_configuration-properties.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_configuration-properties.adoc
index 9480a90..6d88120 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_configuration-properties.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_configuration-properties.adoc
@@ -29,7 +29,7 @@ The following configuration properties are supported:
 |`isis.viewer.restfulobjects.` +
 `honorUiHints`
 | `true`,`false` (`_false_`)
-|A mechanism for reducing the number of round-trips by eagerly rendering collections; discussed xref:ugvro.adoc#___ugvro_ro-spec_extensions_minimizing-round-trips_honor-ui-hints[here].
+|A mechanism for reducing the number of round-trips by eagerly rendering collections; discussed xref:../ugvro/ugvro.adoc#___ugvro_ro-spec_extensions_minimizing-round-trips_honor-ui-hints[here].
 
 |`isis.viewer.restfulobjects.` +
 `strictAcceptChecking`
@@ -38,7 +38,7 @@ The following configuration properties are supported:
 `ContentNegotiationServiceForRestfulObjectsV1_0` service). Will otherwise accept anything.  +
 
 This is convenient because it allows the `Accept` header to be set to that of the
-xref:ugvro.adoc#_ugvro_simplified-representations[Apache Isis profile] for all resources, rather than simply the
+xref:../ugvro/ugvro.adoc#_ugvro_simplified-representations[Apache Isis profile] for all resources, rather than simply the
 handful of resources that supported that profile.
 
 |===
@@ -98,7 +98,7 @@ Nevertheless, those configuration properties are:
 |`isis.viewer.restfulobjects.` +
 `objectPropertyValuesOnly`
 | `true`,`false` (`_false_`)
-| See xref:ugvro.adoc#__ugvro_simplified-representations_configuration-properties_object-property-values-only[discussion] below.
+| See xref:../ugvro/ugvro.adoc#__ugvro_simplified-representations_configuration-properties_object-property-values-only[discussion] below.
 |
 
 |===
@@ -120,7 +120,7 @@ isis.viewer.restfulobjects.suppressMemberDisabledReason=true
 [NOTE]
 ====
 If these configuration settings are set in conjunction with using the
-xref:ugvro.adoc#__ugvro_simplified-representations_apache-isis-profile[Apache Isis profile], then the special `$$ro`
+xref:../ugvro/ugvro.adoc#__ugvro_simplified-representations_apache-isis-profile[Apache Isis profile], then the special `$$ro`
 property in the representations with reflect these settings.
 ====
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_ro-spec.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_ro-spec.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_ro-spec.adoc
index ff033e5..52bd922 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_ro-spec.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_ro-spec.adoc
@@ -132,7 +132,7 @@ Accept: application/xml;x-ro-domain-type="com.mycompany.viewmodels.v2.CustomerVi
 
 The server will use the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`] to attempt to
 transform the domain object into the requested `x-ro-domain-type`.  The whole process is discussed in more detail in
-the xref:ugvro.adoc#_ugvro_architecture[architecture] chapter.
+the xref:../ugvro/ugvro.adoc#_ugvro_architecture[architecture] chapter.
 
 
 [[___ugvro_ro-spec_extensions_content-negotiation_apache-isis-profile]]
@@ -145,7 +145,7 @@ link:http://angular-ui.github.io/bootstrap/[Angular Bootstrap],
 link:http://vitalets.github.io/angular-xeditable/[Angular XEditable],
 link:https://github.com/mgcrea/angular-strap[Angular Strap].
 
-This support is discussed further in the xref:ugvro.adoc#_ugvro_simplified-representations[simplified representations]
+This support is discussed further in the xref:../ugvro/ugvro.adoc#_ugvro_simplified-representations[simplified representations]
 chapter.
 
 
@@ -154,7 +154,7 @@ chapter.
 
 The Restful Objects viewer supports the `x-ro-follow-links` query parameter in a way very similar to that suggested
 in the RO spec, the main point being to avoid the "N+1" problem of too many (slow) network calls.  For example, using
-this feature one can load a grid of data in a single call.  (That said, the xref:ugvro.adoc#_ugvro_simplified-representations[simplified representations]
+this feature one can load a grid of data in a single call.  (That said, the xref:../ugvro/ugvro.adoc#_ugvro_simplified-representations[simplified representations]
 supported by Restful Objects viewer also support this use case, albeit in way that deviates from the RO spec).
 
 This link:https://www.youtube.com/watch?v=hSKnqqBQ7Zo[screencast] demonstrates the Restful Object viewer's support for `x-ro-follow-links` parameter, using the

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations.adoc
index e43ffd5..3a61eb3 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations.adoc
@@ -16,7 +16,7 @@ link:https://github.com/mgcrea/angular-strap[Angular Strap].
 
 As of `1.11.0`, Apache Isis provides support for its own simplified representation for the most commonly-used
 representations.  This is implemented using the `ContentNegotiationService` described in the
-xref:ugvro.adoc#_ugvro_architecture[architecture] chapter.
+xref:../ugvro/ugvro.adoc#_ugvro_architecture[architecture] chapter.
 
 
 
@@ -222,7 +222,7 @@ When an action is invoked, it can return a domain object, a list, a scalar, or r
 === Returning an Object
 
 If the action returned an object, then the domain object representation described
-xref:ugvro.adoc#__ugvro_simplified-representations_domain-object[above] is returned.
+xref:../ugvro/ugvro.adoc#__ugvro_simplified-representations_domain-object[above] is returned.
 
 For example, using the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp], accessing
 this resource:
@@ -273,7 +273,7 @@ Content-Type: application/json;profile="urn:org.apache.isis/v1";repr-type="objec
 
 On the other hand if the action returned a list (a "standalone" collection, then an array representation is returned.
 This is very similar to that returned by a
-xref:ugvro.adoc#__ugvro_simplified-representations_object-collection[(parented) object collection], though with a
+xref:../ugvro/ugvro.adoc#__ugvro_simplified-representations_object-collection[(parented) object collection], though with a
 slightly different `Content-Type` to distinguish.
 
 For example, using the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp], accessing

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_configuration-properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_configuration-properties.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_configuration-properties.adoc
index fd63969..02862e7 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_configuration-properties.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_configuration-properties.adoc
@@ -13,6 +13,6 @@ are limited by the fact that they are global configuration settings, so cannot b
 basis (as is the case with the `Accept` header used for the Apache Isis profile). They have therefore been
 deprecated, and may be removed in the future.
 
-Details can be found in xref:ugvro.adoc#__ugvro_configuration-properties_deprecated[here].
+Details can be found in xref:../ugvro/ugvro.adoc#__ugvro_configuration-properties_deprecated[here].
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_configuration-properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_configuration-properties.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_configuration-properties.adoc
index c33b46c..04be24b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_configuration-properties.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_configuration-properties.adoc
@@ -108,19 +108,19 @@ for further details).
 `maxTitleLengthInParentedTables`
 | +ve integer +
 (`_12_`)
-| See discussion xref:ugvw.adoc#_ugvw_configuration-properties_abbreviating-titles[below].
+| See discussion xref:../ugvw/ugvw.adoc#_ugvw_configuration-properties_abbreviating-titles[below].
 
 |`isis.viewer.wicket.` +
 `maxTitleLengthInStandaloneTables`
 | +ve integer, +
 (`_12_`)
-| See discussion xref:ugvw.adoc#_ugvw_configuration-properties_abbreviating-titles[below].
+| See discussion xref:../ugvw/ugvw.adoc#_ugvw_configuration-properties_abbreviating-titles[below].
 
 |`isis.viewer.wicket.` +
 `maxTitleLengthInTables`
 | +ve integer, +
 (`_12_`)
-| See discussion xref:ugvw.adoc#_ugvw_configuration-properties_abbreviating-titles[below].
+| See discussion xref:../ugvw/ugvw.adoc#_ugvw_configuration-properties_abbreviating-titles[below].
 
 |`isis.viewer.wicket.` +
 `preventDoubleClickForFormSubmit`
@@ -182,13 +182,13 @@ In prototype mode, though, a fixed key will still be used; this saves the develo
 `stripWicketTags`
 | `true`,`false` +
 (`_true_`)
-| Whether to force Wicket tags to be stripped in prototype/development mode.  See discussion xref:ugvw.adoc#_ugvw_configuration-properties_stripped-wicket-tags[below].
+| Whether to force Wicket tags to be stripped in prototype/development mode.  See discussion xref:../ugvw/ugvw.adoc#_ugvw_configuration-properties_stripped-wicket-tags[below].
 
 |`isis.viewer.wicket.` +
 `suppressPasswordReset`
 | `true`,`false` +
 (`_false_`)
-|If user registration is enabled, whether to suppress the "password reset" link on the login page.  See discussion xref:ugvw.adoc#_ugvw_configuration-properties_suppressing-password-reset[below].
+|If user registration is enabled, whether to suppress the "password reset" link on the login page.  See discussion xref:../ugvw/ugvw.adoc#_ugvw_configuration-properties_suppressing-password-reset[below].
 
 |`isis.viewer.wicket.` +
 `suppressRememberMe`
@@ -200,7 +200,7 @@ In prototype mode, though, a fixed key will still be used; this saves the develo
 `suppressSignUp`
 | `true`,`false` +
 (`_false_`)
-|If user registration is enabled, whether to suppress the "sign up" link on the login page.  See discussion xref:ugvw.adoc#_ugvw_configuration-properties_suppressing-sign-up[below].
+|If user registration is enabled, whether to suppress the "sign up" link on the login page.  See discussion xref:../ugvw/ugvw.adoc#_ugvw_configuration-properties_suppressing-sign-up[below].
 
 |`isis.viewer.wicket.` +
 `timestampPattern`
@@ -212,13 +212,13 @@ In prototype mode, though, a fixed key will still be used; this saves the develo
 |`isis.viewer.wicket.` +
 `themes.enabled`
 | comma separated list ...
-| ... of bootswatch themes.  Only applies if `themes.showChooser`==`true`.  See discussion xref:ugvw.adoc#_ugvw_configuration-properties_showing-theme-chooser[below].
+| ... of bootswatch themes.  Only applies if `themes.showChooser`==`true`.  See discussion xref:../ugvw/ugvw.adoc#_ugvw_configuration-properties_showing-theme-chooser[below].
 
 |`isis.viewer.wicket.` +
 `themes.showChooser`
 | `true`,`false` +
 (`_false_`)
-| Whether to show chooser for Bootstrap themes.  See discussion xref:ugvw.adoc#_ugvw_configuration-properties_showing-theme-chooser[below]
+| Whether to show chooser for Bootstrap themes.  See discussion xref:../ugvw/ugvw.adoc#_ugvw_configuration-properties_showing-theme-chooser[below]
 
 |`isis.viewer.wicket.` +
 `useIndicatorForFormSubmit`

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_configuration-properties_abbreviating-titles.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_configuration-properties_abbreviating-titles.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_configuration-properties_abbreviating-titles.adoc
index cd612b7..1aedb81 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_configuration-properties_abbreviating-titles.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_configuration-properties_abbreviating-titles.adoc
@@ -6,7 +6,7 @@
 
 
 
-Objects whose title is overly long can be cumbersome in titles.  The Wicket viewer has a xref:ugvw.adoc#_ugvw_features_titles-in-tables[mechanism to automatically shorten] the titles of objects specified using `@Title`.  As an alternative/in addition, the viewer can also be configured to simply truncate titles longer than a certain length.
+Objects whose title is overly long can be cumbersome in titles.  The Wicket viewer has a xref:../ugvw/ugvw.adoc#_ugvw_features_titles-in-tables[mechanism to automatically shorten] the titles of objects specified using `@Title`.  As an alternative/in addition, the viewer can also be configured to simply truncate titles longer than a certain length.
 
 The properties themselves are:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_configuration-properties_showing-theme-chooser.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_configuration-properties_showing-theme-chooser.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_configuration-properties_showing-theme-chooser.adoc
index afeffc4..5b4c004 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_configuration-properties_showing-theme-chooser.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_configuration-properties_showing-theme-chooser.adoc
@@ -8,7 +8,7 @@
 
 The Wicket viewer uses http://getbootstrap.com/[Bootstrap] styles and components (courtesy of the https://github.com/l0rdn1kk0n/wicket-bootstrap[Wicket Bootstrap] integration).
 
-Unless a xref:ugvw.adoc#_ugvw_customisation_default-theme[default theme has been specified], the viewer uses the default bootstrap theme. However,
+Unless a xref:../ugvw/ugvw.adoc#_ugvw_customisation_default-theme[default theme has been specified], the viewer uses the default bootstrap theme. However,
 the viewer can also be configured to allow the end-user to switch theme to another theme, in particular one of those provided by http://bootswatch.com[bootswatch.com].
 
 This is done using the following configuration property (in `WEB-INF/viewer_wicket.properties`):
@@ -37,7 +37,7 @@ where the value is the list of themes (from http://bootswatch.com[bootswatch.com
 
 [TIP]
 ====
-You can also develop and install a custom themes (eg to fit your company's look-n-feel/interface guidelines); see the xref:ugvw.adoc#_ugvw_extending_custom-bootstrap-theme[Extending] chapter for further details.
+You can also develop and install a custom themes (eg to fit your company's look-n-feel/interface guidelines); see the xref:../ugvw/ugvw.adoc#_ugvw_extending_custom-bootstrap-theme[Extending] chapter for further details.
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_configuration-properties_suppressing-password-reset.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_configuration-properties_suppressing-password-reset.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_configuration-properties_suppressing-password-reset.adoc
index 240e7e4..daf1226 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_configuration-properties_suppressing-password-reset.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_configuration-properties_suppressing-password-reset.adoc
@@ -39,7 +39,7 @@ Typically this should be added to the `viewer_wicket.properties` file (in `WEB-I
 
 == See also
 
-The xref:ugvw.adoc#_ugvw_configuration-properties_suppressing-sign-up[sign up link] can be suppressed in a similar manner.
+The xref:../ugvw/ugvw.adoc#_ugvw_configuration-properties_suppressing-sign-up[sign up link] can be suppressed in a similar manner.
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_configuration-properties_suppressing-sign-up.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_configuration-properties_suppressing-sign-up.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_configuration-properties_suppressing-sign-up.adoc
index 4afb734..6d20fea 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_configuration-properties_suppressing-sign-up.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_configuration-properties_suppressing-sign-up.adoc
@@ -41,7 +41,7 @@ isis.viewer.wicket.suppressSignUp=true
 
 == See also
 
-The xref:ugvw.adoc#_ugvw_configuration-properties_suppressing-password-reset[password reset link] can be suppressed in a similar manner.
+The xref:../ugvw/ugvw.adoc#_ugvw_configuration-properties_suppressing-password-reset[password reset link] can be suppressed in a similar manner.
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_customisation_about-page.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_customisation_about-page.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_customisation_about-page.adoc
index 7218453..3e4f01b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_customisation_about-page.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_customisation_about-page.adoc
@@ -17,7 +17,7 @@ image::{_imagesdir}about-page/about-page.png[width="800px",link="{_imagesdir}abo
 
 [NOTE]
 ====
-Note that this screenshot shows an earlier version of the xref:ugvw.adoc#[Wicket viewer] UI (specifically, pre 1.8.0).
+Note that this screenshot shows an earlier version of the xref:../ugvw/ugvw.adoc#[Wicket viewer] UI (specifically, pre 1.8.0).
 ====
 
 Note that the `Build-Time` attribute has been used as the version number. The Wicket viewer is hard-coded to search for specific attributes and use as the application version. In order, it searches for:

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_customisation_cheap-n-cheerful-theme.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_customisation_cheap-n-cheerful-theme.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_customisation_cheap-n-cheerful-theme.adoc
index 67f3313..0bd3795 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_customisation_cheap-n-cheerful-theme.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_customisation_cheap-n-cheerful-theme.adoc
@@ -22,7 +22,7 @@ You can therefore use this CSS class as a way of building your own "theme" for t
 
 [TIP]
 ====
-Alternatively you could "do it properly" and create your xref:ugvw.adoc#_ugvw_extending_custom-bootstrap-theme[own Bootstrap theme], as described in the xref:ugbtb.adoc#[Extending] chapter.
+Alternatively you could "do it properly" and create your xref:../ugvw/ugvw.adoc#_ugvw_extending_custom-bootstrap-theme[own Bootstrap theme], as described in the xref:../ugbtb/ugbtb.adoc#[Extending] chapter.
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_customisation_custom-javascript.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_customisation_custom-javascript.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_customisation_custom-javascript.adoc
index 36d303d..cee1faf 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_customisation_custom-javascript.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_customisation_custom-javascript.adoc
@@ -12,7 +12,7 @@ The Wicket viewer ships with embedded JQuery, so this can be leveraged to perfor
 ====
 Just because something is possible, it doesn't necessarily mean we encourage it.  Please be aware that there is no formal API for any custom javascript that you might implement to target; future versions of Apache Isis might break your code.
 
-If possible, consider using the `ComponentFactory` API described in the xref:ugvw.adoc#_ugvw_extending[Extending] chapter.
+If possible, consider using the `ComponentFactory` API described in the xref:../ugvw/ugvw.adoc#_ugvw_extending[Extending] chapter.
 ====
 
 To register your Javascript code, adjusting the Guice bindings (part of Apache Isis' bootstrapping) in your custom subclass of `IsisWicketApplication`:

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_customisation_default-theme.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_customisation_default-theme.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_customisation_default-theme.adoc
index 9de200f..837c941 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_customisation_default-theme.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_customisation_default-theme.adoc
@@ -21,7 +21,7 @@ protected void init() {
 }
 ----
 
-If you have developed a custom Bootstrap theme (as described xref:ugvw.adoc#_ugvw_extending_custom-bootstrap-theme[here]) then this can also be specified using the https://github.com/l0rdn1kk0n/wicket-bootstrap/wiki/Themes[Wicket Bootstrap API].
+If you have developed a custom Bootstrap theme (as described xref:../ugvw/ugvw.adoc#_ugvw_extending_custom-bootstrap-theme[here]) then this can also be specified using the https://github.com/l0rdn1kk0n/wicket-bootstrap/wiki/Themes[Wicket Bootstrap API].
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_customisation_tweaking-css-classes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_customisation_tweaking-css-classes.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_customisation_tweaking-css-classes.adoc
index 1413b91..14921f4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_customisation_tweaking-css-classes.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_customisation_tweaking-css-classes.adoc
@@ -92,7 +92,7 @@ div.x-myapp-highlight span.scalarName {
 }
 ----
 
-Note also that instead of using `@PropertyLayout(cssClass=...)` annotation, you can also specify the CSS style using a xref:ugvw.adoc#_ugvw_layout_file-based[layout file].
+Note also that instead of using `@PropertyLayout(cssClass=...)` annotation, you can also specify the CSS style using a xref:../ugvw/ugvw.adoc#_ugvw_layout_file-based[layout file].
 
 
 
@@ -188,7 +188,7 @@ For example:
 </div>
 ----
 <1> the parent class identifier
-<2> the collection identifier. This element's class also has the entity type within the collection (as xref:ugvw.adoc#__ugvw_customisation_tweaking-css-classes_columns-in-tables_globally[discussed above]).
+<2> the collection identifier. This element's class also has the entity type within the collection (as xref:../ugvw/ugvw.adoc#__ugvw_customisation_tweaking-css-classes_columns-in-tables_globally[discussed above]).
 
 Using this, the `productRef` property could be targeted using:
 
@@ -232,7 +232,7 @@ Standalone collections will be wrapped in a ``<div>`` that identifies the action
     </div>
 </div>
 ----
-<1> action identifier.  This element's class also identifies the entity type within the collection (as xref:ugvw.adoc#__ugvw_customisation_tweaking-css-classes_columns-in-tables_globally[discussed above]).
+<1> action identifier.  This element's class also identifies the entity type within the collection (as xref:../ugvw/ugvw.adoc#__ugvw_customisation_tweaking-css-classes_columns-in-tables_globally[discussed above]).
 
 Using this, the `quantity` property could be targeted using:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_extending.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_extending.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_extending.adoc
index 6100909..d35b10c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_extending.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_extending.adoc
@@ -7,13 +7,13 @@
 
 The Wicket viewer allows you to customize the GUI in several (progressively more sophisticated) ways:
 
-* by xref:ugvw.adoc#_ugvw_customisation_tweaking-css-classes[tweaking the UI using CSS]
-* by xref:ugvw.adoc#_ugvw_customisation_custom-javascript[tweaking the UI using Javascript]
-* by writing a xref:ugvw.adoc#_ugvw_extending_custom-bootstrap-theme[custom bootstrap theme]
-* by xref:ugvw.adoc#_ugvw_extending_replacing-page-elements[replacing elements of the page] using the `ComponentFactory` interface
-* by implementing xref:ugvw.adoc#_ugvw_extending_custom-pages[replacement page implementations] for the standard page types
+* by xref:../ugvw/ugvw.adoc#_ugvw_customisation_tweaking-css-classes[tweaking the UI using CSS]
+* by xref:../ugvw/ugvw.adoc#_ugvw_customisation_custom-javascript[tweaking the UI using Javascript]
+* by writing a xref:../ugvw/ugvw.adoc#_ugvw_extending_custom-bootstrap-theme[custom bootstrap theme]
+* by xref:../ugvw/ugvw.adoc#_ugvw_extending_replacing-page-elements[replacing elements of the page] using the `ComponentFactory` interface
+* by implementing xref:../ugvw/ugvw.adoc#_ugvw_extending_custom-pages[replacement page implementations] for the standard page types
 
-The first two of these options are discussed in the xref:ugvw.adoc#[Wicket viewer] chapter.  This chapter describes the remaining "heavier-weight/more powerful" options.
+The first two of these options are discussed in the xref:../ugvw/ugvw.adoc#[Wicket viewer] chapter.  This chapter describes the remaining "heavier-weight/more powerful" options.
 
 The chapter wraps up with a technique for prototyping, allowing user/passwords to be specified as query arguments.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_extending_custom-bootstrap-theme.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_extending_custom-bootstrap-theme.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_extending_custom-bootstrap-theme.adoc
index 472fdd6..e52d7d5 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_extending_custom-bootstrap-theme.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_extending_custom-bootstrap-theme.adoc
@@ -8,7 +8,7 @@
 
 The Apache Isis Wicket viewer uses http://getbootstrap.com/[Bootstrap] styles and components (courtesy of the https://github.com/l0rdn1kk0n/wicket-bootstrap[Wicket Bootstrap] integration).
 
-By default the viewer uses the default bootstrap theme. It is possible to configure the Wicket viewer to allow the user to xref:ugvw.adoc#_ugvw_configuration-properties_showing-theme-chooser[select other themes] provided by http://bootswatch.com[bootswatch.com], and if required one of these can be xref:ugvw.adoc#_ugvw_customisation_default-theme[set as the default].
+By default the viewer uses the default bootstrap theme. It is possible to configure the Wicket viewer to allow the user to xref:../ugvw/ugvw.adoc#_ugvw_configuration-properties_showing-theme-chooser[select other themes] provided by http://bootswatch.com[bootswatch.com], and if required one of these can be xref:../ugvw/ugvw.adoc#_ugvw_customisation_default-theme[set as the default].
 
 However, you may instead want to write your own custom theme, for example to fit your company's look-n-feel/interface guidelines. This is done by implementing https://github.com/l0rdn1kk0n/wicket-bootstrap[Wicket Bootstrap]\u2019s `de.agilecoders.wicket.core.settings.ITheme` class. This defines:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_extending_custom-pages.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_extending_custom-pages.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_extending_custom-pages.adoc
index 1f143c1..0a37f43 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_extending_custom-pages.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_extending_custom-pages.adoc
@@ -6,7 +6,7 @@
 
 
 
-In the vast majority of cases customization should be sufficient by xref:ugvw.adoc#_ugvw_extending_replacing-page-elements[replacing elements of a page]. However, it is also possible to define an entirely new page for a given page type.
+In the vast majority of cases customization should be sufficient by xref:../ugvw/ugvw.adoc#_ugvw_extending_replacing-page-elements[replacing elements of a page]. However, it is also possible to define an entirely new page for a given page type.
 
 Isis defines eight page types (see the `org.apache.isis.viewer.wicket.model.models.PageType` enum):
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_extending_replacing-page-elements.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_extending_replacing-page-elements.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_extending_replacing-page-elements.adoc
index 782596b..bd369e1 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_extending_replacing-page-elements.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_extending_replacing-page-elements.adoc
@@ -27,7 +27,7 @@ There will typically be only one `ComponentFactory` capable of rendering a parti
 
 [NOTE]
 ====
-There is one refinement to the above algorithm where multiple component factories might be used to render an object; this is discussed in xref:ugvw.adoc#__ugvw_extending_replacing-page-elements_collections[Additional Views of Collections], below.
+There is one refinement to the above algorithm where multiple component factories might be used to render an object; this is discussed in xref:../ugvw/ugvw.adoc#__ugvw_extending_replacing-page-elements_collections[Additional Views of Collections], below.
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_features_blob-attachments.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_features_blob-attachments.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_features_blob-attachments.adoc
index 59579a3..8114efd 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_features_blob-attachments.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_features_blob-attachments.adoc
@@ -28,7 +28,7 @@ image::{_imagesdir}blob-attachments/010-attachment-field-940.png[width="800px",l
 
 [NOTE]
 ====
-Note that these screenshots show an earlier version of the xref:ugvw.adoc#[Wicket viewer] UI (specifically, pre 1.8.0).
+Note that these screenshots show an earlier version of the xref:../ugvw/ugvw.adoc#[Wicket viewer] UI (specifically, pre 1.8.0).
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_features_bookmarked-pages.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_features_bookmarked-pages.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_features_bookmarked-pages.adoc
index 9ce7313..2424d19 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_features_bookmarked-pages.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_features_bookmarked-pages.adoc
@@ -23,7 +23,7 @@ image::{_imagesdir}bookmarked-pages/panel.png[width="800px",link="{_imagesdir}bo
 
 [NOTE]
 ====
-Note that these screenshots show an earlier version of the xref:ugvw.adoc#[Wicket viewer] UI (specifically, pre 1.8.0).
+Note that these screenshots show an earlier version of the xref:../ugvw/ugvw.adoc#[Wicket viewer] UI (specifically, pre 1.8.0).
 ====
 
 Note how the list contains both domain objects and an action ("not yet complete").
@@ -92,7 +92,7 @@ Alternatively, `alt+[` will toggle open/close the panel; it can also be closed u
 
 === Related functionality
 
-The xref:ugvw.adoc#_ugvw_features_recent-pages[Recent Pages] also lists recently visited pages, selected from a drop-down.
+The xref:../ugvw/ugvw.adoc#_ugvw_features_recent-pages[Recent Pages] also lists recently visited pages, selected from a drop-down.
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_features_hints-and-copy-url.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_features_hints-and-copy-url.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_features_hints-and-copy-url.adoc
index 7948b12..c528c43 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_features_hints-and-copy-url.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_features_hints-and-copy-url.adoc
@@ -27,7 +27,7 @@ image::{_imagesdir}copy-link/010-copy-link-button.png[width="800px",link="{_imag
 
 [NOTE]
 ====
-Note that these screenshots show an earlier version of the xref:ugvw.adoc#[Wicket viewer] UI (specifically, pre 1.8.0).
+Note that these screenshots show an earlier version of the xref:../ugvw/ugvw.adoc#[Wicket viewer] UI (specifically, pre 1.8.0).
 ====
 
 Clicking on this button brings up a dialog with the URL preselected:

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_features_recent-pages.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_features_recent-pages.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_features_recent-pages.adoc
index 00473b1..114f29c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_features_recent-pages.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_features_recent-pages.adoc
@@ -19,7 +19,7 @@ image::{_imagesdir}recent-pages/recent-pages.png[width="800px",link="{_imagesdir
 
 [NOTE]
 ====
-Note that this screenshot show an earlier version of the xref:ugvw.adoc#[Wicket viewer] UI (specifically, pre 1.8.0).
+Note that this screenshot show an earlier version of the xref:../ugvw/ugvw.adoc#[Wicket viewer] UI (specifically, pre 1.8.0).
 ====
 
 
@@ -42,7 +42,7 @@ Selecting the domain object from the list causes the viewer to automatically nav
 
 == Related functionality
 
-The xref:ugvw.adoc#_ugvw_features_bookmarked-pages[bookmarked pages] (sliding panel) also provides links to recently visited objects, but only those explicitly marked as `@DomainObject(bookmarking=...)`.  The bookmarks panel also nests related objects together hierarchically (the recent pages drop-down does not).
+The xref:../ugvw/ugvw.adoc#_ugvw_features_bookmarked-pages[bookmarked pages] (sliding panel) also provides links to recently visited objects, but only those explicitly marked as `@DomainObject(bookmarking=...)`.  The bookmarks panel also nests related objects together hierarchically (the recent pages drop-down does not).
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_features_titles-in-tables.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_features_titles-in-tables.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_features_titles-in-tables.adoc
index 0a925a0..c245791 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_features_titles-in-tables.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_features_titles-in-tables.adoc
@@ -72,5 +72,5 @@ The above annotations mean that titles usually "just work", altering according t
 
 [TIP]
 ====
-It is also possible to configure the Wicket viewer to xref:ugvw.adoc#_ugvw_configuration-properties_abbreviating-titles[abbreviate titles or suppress them] completely.
+It is also possible to configure the Wicket viewer to xref:../ugvw/ugvw.adoc#_ugvw_configuration-properties_abbreviating-titles[abbreviate titles or suppress them] completely.
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_features_user-registration.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_features_user-registration.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_features_user-registration.adoc
index c9426f7..c95bec1 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_features_user-registration.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_features_user-registration.adoc
@@ -74,7 +74,7 @@ There are two prerequisites:
 
 The latter is required if you are using the default email notification service and email service. If you are using your own alternative implementation of the email notification service then it may be omitted (and configure your own alternative implementation as required).
 
-It is also possible to configure the Wicket viewer to suppress xref:ugvw.adoc#_ugvw_configuration-properties_suppressing-sign-up[the sign-up page link] and/or the xref:ugvw.adoc#_ugvw_configuration-properties_suppressing-password-reset[password reset page].
+It is also possible to configure the Wicket viewer to suppress xref:../ugvw/ugvw.adoc#_ugvw_configuration-properties_suppressing-sign-up[the sign-up page link] and/or the xref:../ugvw/ugvw.adoc#_ugvw_configuration-properties_suppressing-password-reset[password reset page].
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_isis-addons.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_isis-addons.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_isis-addons.adoc
index 2a43ad2..c35ed25 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_isis-addons.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_isis-addons.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-The (non-ASF) link:http://www.isisaddons.org[Isis Addons] website provides a number of extensions to the Wicket viewer (leveraging the APIs described in xref:ugvw.adoc#_ugvw_extending[Extending the Wicket viewer] section, later.  While you are free to fork and adapt any of them to your needs, they are also intended for use "out-of-the-box".
+The (non-ASF) link:http://www.isisaddons.org[Isis Addons] website provides a number of extensions to the Wicket viewer (leveraging the APIs described in xref:../ugvw/ugvw.adoc#_ugvw_extending[Extending the Wicket viewer] section, later.  While you are free to fork and adapt any of them to your needs, they are also intended for use "out-of-the-box".
 
 At the time of writing the addons available are:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_annotation-based.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_annotation-based.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_annotation-based.adoc
index efc0d0c..1261580 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_annotation-based.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_annotation-based.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-Metadata providing UI hints can be specified either using annotations, or using a xref:ugvw.adoc#_ugvw_layout_file-based[`layout.xml`] file.
+Metadata providing UI hints can be specified either using annotations, or using a xref:../ugvw/ugvw.adoc#_ugvw_layout_file-based[`layout.xml`] file.
 
 In most cases you will probably want to use the file-based approach: changes to file layouts are picked up dynamically, and using a file also allows tabs and tab groups to be specified: this is not supported using annotations.
 
@@ -106,7 +106,7 @@ The property groups/fieldsets in this case are those that are inferred from the
 
 [TIP]
 ====
-It is also possible to combine `@MemberOrder` with a xref:ugvw.adoc#_ugvw_layout_xml[file-based layout].
+It is also possible to combine `@MemberOrder` with a xref:../ugvw/ugvw.adoc#_ugvw_layout_xml[file-based layout].
 The layout file defines only the regions of a grid structure (fieldsets/columns etc), but does __not__ specify the properties/collections/actions within those grid regions.
 The `@MemberOrder` annotation in effect "binds" the properties or collections to those regions of the grid.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_application-menu.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_application-menu.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_application-menu.adoc
index f849d66..3fb3ba5 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_application-menu.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_application-menu.adoc
@@ -167,5 +167,5 @@ Meanwhile the http://github.com/isisaddons/isis-module-devutils[devutils] module
 so forth - on a "Prototyping" top-level menu, on the SECONDARY menu bar.
 
 Currently there is no facility to alter the placement of these services. However, their UI can be suppressed
-using security or using a xref:ugbtb.adoc#_ugbtb_decoupling_vetoing-visibility[vetoing subscriber].
+using security or using a xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_vetoing-visibility[vetoing subscriber].
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_file-based.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_file-based.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_file-based.adoc
index 513542a..5676d55 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_file-based.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_file-based.adoc
@@ -6,7 +6,7 @@
 
 
 
-Metadata providing UI hints can be specified either xref:ugvw.adoc#_ugvw_layout_annotation-based[using annotations], or using an `Xxx.layout.xml` file (where `Xxx` is the entity or view model object to be rendered).
+Metadata providing UI hints can be specified either xref:../ugvw/ugvw.adoc#_ugvw_layout_annotation-based[using annotations], or using an `Xxx.layout.xml` file (where `Xxx` is the entity or view model object to be rendered).
 
 Using a file-based layout has the huge benefit that the layout can be updated without requiring a recompile of the code and redeploy of the app.
 Many developers also find it easier to rationalize about layout when all the hints are collated together in a single place (rather than scattered across the class members as annotations).
@@ -39,7 +39,7 @@ The layout file distinguishes between two types of element:
 
 * those that define a grid structure, of: rows, columns, tab groups and tabs. +
 +
-The rows and columns are closely modelled on link:getbootstrap.com[Bootstrap 3] (used in the implementation of the xref:ugvw.adoc[Wicket viewer]).
+The rows and columns are closely modelled on link:getbootstrap.com[Bootstrap 3] (used in the implementation of the xref:../ugvw/ugvw.adoc[Wicket viewer]).
 
 * those that defines common components, of: fieldsets (previously called member groups or property groups), properties, collections, actions and also the title/icon of the domain object itself.
 

[37/58] [abbrv] isis git commit: ISIS-1521: reorganizes security chapters/sections

[da...@apache.org]

ISIS-1521: reorganizes security chapters/sections


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/45db638e
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/45db638e
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/45db638e

Branch: refs/heads/wip
Commit: 45db638ed1073af73ee49082a5c268d3f058b86f
Parents: bef8814
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Fri Apr 14 16:31:59 2017 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Thu Apr 20 09:09:30 2017 +0100

----------------------------------------------------------------------
 .../guides/dg/_dg_asciidoc-templates.adoc       |   4 +-
 .../asciidoc/guides/dg/_dg_hints-and-tips.adoc  |   2 +-
 .../guides/ugbtb/_ugbtb_hints-and-tips.adoc     |   2 +-
 .../guides/ugodn/_ugodn_hints-and-tips.adoc     |   2 +-
 .../guides/ugsec/_ugsec_hints-and-tips.adoc     |   3 +-
 .../_ugsec_hints-and-tips_shiro-caching.adoc    |  41 ++++++
 .../guides/ugsec/_ugsec_shiro-caching.adoc      |  41 ------
 .../guides/ugsec/_ugsec_shiro-ini-realm.adoc    | 133 -----------------
 ...shiro-isis-enhanced-wildcard-permission.adoc |   2 +-
 .../ugsec/_ugsec_shiro-isis-ldap-realm.adoc     | 146 -------------------
 ..._shiro-isisaddons-security-module-realm.adoc |  36 -----
 .../guides/ugsec/_ugsec_shiro-jdbc-realm.adoc   | 113 --------------
 .../_ugsec_shiro-realm-implementations.adoc     |  15 ++
 ...c_shiro-realm-implementations_ini-realm.adoc | 133 +++++++++++++++++
 ...o-realm-implementations_isis-ldap-realm.adoc | 146 +++++++++++++++++++
 ...ations_isisaddons-security-module-realm.adoc |  36 +++++
 ..._shiro-realm-implementations_jdbc-realm.adoc | 113 ++++++++++++++
 .../src/main/asciidoc/guides/ugsec/ugsec.adoc   |   6 +-
 .../guides/ugvro/_ugvro_hints-and-tips.adoc     |   2 +-
 .../guides/ugvw/_ugvw_hints-and-tips.adoc       |   2 +-
 20 files changed, 495 insertions(+), 483 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/45db638e/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc-templates.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc-templates.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc-templates.adoc
index 8ccd418..44b6549 100644
--- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc-templates.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc-templates.adoc
@@ -349,9 +349,9 @@ A hyperlink to a bookmark within the Secrurity guide, where:
 
 for example:
 
-`\xref:../ugsec/ugsec.adoc#_ugsec_shiro-caching[Caching and other Shiro Features]`
+`\xref:../ugsec/ugsec.adoc#_ugsec_hints-and-tips_shiro-caching[Caching and other Shiro Features]`
 
-|xref:../ugsec/ugsec.adoc#_ugsec_shiro-caching[Caching and other Shiro Features]
+|xref:../ugsec/ugsec.adoc#_ugsec_hints-and-tips_shiro-caching[Caching and other Shiro Features]
 
 
 |`adugtst`

http://git-wip-us.apache.org/repos/asf/isis/blob/45db638e/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc
index 094550e..f0ed4c6 100644
--- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc
@@ -10,7 +10,7 @@ This chapter provides some solutions for problems we've encountered ourselves or
 
 See also hints-n-tips chapters in the:
 
-* the xref:../dg/dg.adoc#_ugvw_hints-and-tips[Developers'] guide (this chapter)
+* the xref:../dg/dg.adoc#_dg_hints-and-tips[Developers'] guide (this chapter)
 
 * the xref:../ugvw/ugvw.adoc#_ugvw_hints-and-tips[Wicket viewer] guide
 

http://git-wip-us.apache.org/repos/asf/isis/blob/45db638e/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips.adoc
index 2c78959..51c76f0 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips.adoc
@@ -10,7 +10,7 @@ This chapter provides some solutions for problems we've encountered ourselves or
 
 See also hints-n-tips chapters in the:
 
-* the xref:../dg/dg.adoc#_ugvw_hints-and-tips[Developers'] guide
+* the xref:../dg/dg.adoc#_dg_hints-and-tips[Developers'] guide
 
 * the xref:../ugvw/ugvw.adoc#_ugvw_hints-and-tips[Wicket viewer] guide
 

http://git-wip-us.apache.org/repos/asf/isis/blob/45db638e/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips.adoc
index 39ca25c..61806ac 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips.adoc
@@ -9,7 +9,7 @@ This chapter provides some solutions for problems we've encountered ourselves or
 
 See also hints-n-tips chapters in the:
 
-* the xref:../dg/dg.adoc#_ugvw_hints-and-tips[Developers'] guide
+* the xref:../dg/dg.adoc#_dg_hints-and-tips[Developers'] guide
 
 * the xref:../ugvw/ugvw.adoc#_ugvw_hints-and-tips[Wicket viewer] guide
 

http://git-wip-us.apache.org/repos/asf/isis/blob/45db638e/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_hints-and-tips.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_hints-and-tips.adoc b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_hints-and-tips.adoc
index 97ccf36..71cef6b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_hints-and-tips.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_hints-and-tips.adoc
@@ -11,7 +11,7 @@ This chapter provides some solutions for problems we've encountered ourselves or
 
 See also hints-n-tips chapters in the:
 
-* the xref:../dg/dg.adoc#_ugvw_hints-and-tips[Developers'] guide
+* the xref:../dg/dg.adoc#_dg_hints-and-tips[Developers'] guide
 
 * the xref:../ugvw/ugvw.adoc#_ugvw_hints-and-tips[Wicket viewer] guide
 
@@ -26,3 +26,4 @@ See also hints-n-tips chapters in the:
 
 
 include::_ugsec_hints-and-tips_configuring-isis-to-use-bypass.adoc[leveloffset=+1]
+include::_ugsec_hints-and-tips_shiro-caching.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/45db638e/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_hints-and-tips_shiro-caching.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_hints-and-tips_shiro-caching.adoc b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_hints-and-tips_shiro-caching.adoc
new file mode 100644
index 0000000..190a26c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_hints-and-tips_shiro-caching.adoc
@@ -0,0 +1,41 @@
+[[_ugsec_hints-and-tips_shiro-caching]]
+= 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/
+
+
+We don't want to repeat the entire link:http://shiro.apache.org/documentation.html[Shiro documentation set] here, but we should flag a number of otherof other features that are worth checking out.
+
+
+
+
+== Caching
+
+To ensure that security operations does not impede performance, Shiro supports caching.  For example, this sets up a simple memory-based cache manager:
+
+[source,ini]
+----
+memoryCacheManager = org.apache.shiro.cache.MemoryConstrainedCacheManager
+securityManager.cacheManager = $memoryCacheManager
+----
+
+Other implementations can be plugged in; see the Shiro link:http://shiro.apache.org/caching.html[documentation] for further details.
+
+
+
+
+== Further Reading
+
+
+* Shiro's documentation page can be found link:http://shiro.apache.org/documentation.html[here].
+
+* community-contributed articles can be found link:http://shiro.apache.org/articles.html[here]. +
++
+These include for instance link:http://meri-stuff.blogspot.co.uk/2011/04/apache-shiro-part-2-realms-database-and.html[this interesting article] describing how to perform certificate-based authentication (ie login using Google or Facebook credentials).
+
+
+
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/45db638e/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-caching.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-caching.adoc b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-caching.adoc
deleted file mode 100644
index c97fa72..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-caching.adoc
+++ /dev/null
@@ -1,41 +0,0 @@
-[[_ugsec_shiro-caching]]
-= 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/
-
-
-We don't want to repeat the entire link:http://shiro.apache.org/documentation.html[Shiro documentation set] here, but we should flag a number of otherof other features that are worth checking out.
-
-
-
-
-== Caching
-
-To ensure that security operations does not impede performance, Shiro supports caching.  For example, this sets up a simple memory-based cache manager:
-
-[source,ini]
-----
-memoryCacheManager = org.apache.shiro.cache.MemoryConstrainedCacheManager
-securityManager.cacheManager = $memoryCacheManager
-----
-
-Other implementations can be plugged in; see the Shiro link:http://shiro.apache.org/caching.html[documentation] for further details.
-
-
-
-
-== Further Reading
-
-
-* Shiro's documentation page can be found link:http://shiro.apache.org/documentation.html[here].
-
-* community-contributed articles can be found link:http://shiro.apache.org/articles.html[here]. +
-+
-These include for instance link:http://meri-stuff.blogspot.co.uk/2011/04/apache-shiro-part-2-realms-database-and.html[this interesting article] describing how to perform certificate-based authentication (ie login using Google or Facebook credentials).
-
-
-
-
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/45db638e/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-ini-realm.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-ini-realm.adoc b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-ini-realm.adoc
deleted file mode 100644
index 3e3ce94..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-ini-realm.adoc
+++ /dev/null
@@ -1,133 +0,0 @@
-[[_ugsec_shiro-ini-realm]]
-= 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/
-
-
-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:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] is configured to use this realm.
-
-The diagram below shows the Isis and components involved:
-
-image::{_imagesdir}security/security-apis-impl/configure-shiro-to-use-ini-realm.PNG[width="600px"]
-
-The realm is responsible for validating the user credentials, and then creates a Shiro link:http://shiro.apache.org/static/latest/apidocs/org/apache/shiro/subject/Subject.html[`Subject`] which represents the user (for the current request).  Apache Isis `Authenticator` component then interacts with the `Subject` in order to check permissions.
-
-
-
-
-== Shiro Configuration
-
-To use the built-in `IniRealm`, we add the following to `WEB-INF/shiro.ini`:
-
-[source,ini]
-----
-securityManager.realms = $iniRealm
-----
-
-(Unlike other realms) there is no need to "define" `$iniRealm`; it is automatically available to us.
-
-Specifying `$iniRealm` means that the usernames/passwords, roles and permissions are read from the `shiro.ini` file itself.  Specifically:
-
-* the users/passwords and their roles from the `[users]` sections;
-* the roles are mapped to permissions in the `[roles]` section.
-
-The format of these is described below.
-
-=== `[users]` section
-
-This section lists users, passwords and their roles.
-
-For example:
-
-[source,ini]
-----
-sven = pass, admin_role
-dick = pass, user_role, analysis_role, self-install_role
-bob  = pass, user_role, self-install_role
-----
-The first value is the password (eg "pass", the remaining values are the role(s).
-
-
-=== `[roles]` section
-
-This section lists roles and their corresponding permissions.
-
-For example:
-
-[source,ini]
-----
-user_role = *:ToDoItems:*:*,\
-            *:ToDoItem:*:*,\
-            *:ToDoAppDashboard:*:*
-analysis_role = *:ToDoItemAnalysis:*:*,\
-            *:ToDoItemsByCategoryViewModel:*:*,\
-            *:ToDoItemsByDateRangeViewModel:*:*
-self-install_role = *:ToDoItemsFixturesService:install:*
-admin_role = *
-----
-
-The value is a comma-separated list of permissions for the role.  The format is:
-
-[source,ini]
-----
-packageName:className:memberName:r,w
-----
-
-where:
-
-* `memberName` is the property, collection or action name.
-* `r` indicates that the member is visible
-* `w` indicates that the member is usable (editable or invokable)
-
-and where each of the parts of the permission string can be wildcarded using `*`.
-
-Because these are wildcards, a '*' can be used at any level. Additionally, missing levels assume wildcards.
-
-Thus:
-
-[source,ini]
-----
-com.mycompany.myapp:Customer:firstName:r,w   # view or edit customer's firstName
-com.mycompany.myapp:Customer:lastName:r      # view customer's lastName only
-com.mycompany.myapp:Customer:placeOrder:*    # view and invoke placeOrder action
-com.mycompany.myapp:Customer:placeOrder      # ditto
-com.mycompany.myapp:Customer:*:r             # view all customer class members
-com.mycompany.myapp:*:*:r                    # view-only access for all classes in myapp package
-com.mycompany.myapp:*:*:*                    # view/edit for all classes in myapp package
-com.mycompany.myapp:*:*                      # ditto
-com.mycompany.myapp:*                        # ditto
-com.mycompany.myapp                          # ditto
-*                                            # view/edit access to everything
-----
-
-[TIP]
-====
-The format of the permissions string is configurable in Shiro, and Apache Isis uses this to provide an extended wildcard format, described xref:../ugsec/ugsec.adoc#_ugsec_shiro-isis-enhanced-wildcard-permission[here].
-====
-
-
-
-
-== Externalized IniRealm
-
-There's no requirement for all users/roles to be defined in the `shiro.ini` file.  Instead, a realm can be defined that loads its users/roles from some other resource.
-
-For example:
-
-[source,ini]
-----
-$realm1=org.apache.shiro.realm.text.IniRealm # <1>
-realm1.resourcePath=classpath:webapp/realm1.ini # <2>
-----
-<1> happens to (coincidentally) be the link:http://shiro.apache.org/static/latest/apidocs/org/apache/shiro/realm/text/IniRealm.html[same implementation] as Shiro's built-in $iniRealm
-<2> in this case load the users/roles from the `src/main/resources/webapp/realm1.ini` file.
-
-Note that a URL could be provided as the `resourcePath`, so a centralized config file could be used.  Even so, the
-
-[NOTE]
-====
-If configured this way then the `[users]` and `[roles]` sections of `shiro.ini` become unused. Instead, the corresponding sections from for `realm1.ini` are used instead.
-====

http://git-wip-us.apache.org/repos/asf/isis/blob/45db638e/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-isis-enhanced-wildcard-permission.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-isis-enhanced-wildcard-permission.adoc b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-isis-enhanced-wildcard-permission.adoc
index 241a297..82b1b5d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-isis-enhanced-wildcard-permission.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-isis-enhanced-wildcard-permission.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-If using the text-based xref:../ugsec/ugsec.adoc#_ugsec_shiro-ini-realm[`IniRealm`] or xref:../ugsec/ugsec.adoc#_ugsec_shiro-isis-ldap-realm[Isis' LDAP realm], then note that Shiro also allows the string representation of the permissions to be mapped (resolved) to alternative `Permission` instances.  Apache Isis provides its own `IsisPermission` which introduces the concept of a "veto".
+If using the text-based xref:../ugsec/ugsec.adoc#_ugsec_shiro-realm-implementations_ini-realm[`IniRealm`] or xref:../ugsec/ugsec.adoc#_ugsec_shiro-realm-implementations_isis-ldap-realm[Isis' LDAP realm], then note that Shiro also allows the string representation of the permissions to be mapped (resolved) to alternative `Permission` instances.  Apache Isis provides its own `IsisPermission` which introduces the concept of a "veto".
 
 A vetoing permission is one that prevents access to a feature, rather than grants it.  This is useful in some situations where most users have access to most features, and only a small number of features are particularly sensitive.  The configuration can therefore be set up to grant fairly broad-brush permissions and then veto permission for the sensitive features for those users that do not have access.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/45db638e/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-isis-ldap-realm.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-isis-ldap-realm.adoc b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-isis-ldap-realm.adoc
deleted file mode 100644
index c2a2ec6..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-isis-ldap-realm.adoc
+++ /dev/null
@@ -1,146 +0,0 @@
-[[_ugsec_shiro-isis-ldap-realm]]
-= 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/
-
-
-Isis ships with an implementation of http://shiro.apache.org[Apache Shiro]'s `Realm` class that allows user authentication and authorization to be performed against an LDAP server.
-
-image::{_imagesdir}security/security-apis-impl/configure-shiro-to-use-isis-ldap-realm.PNG[width="600px"]
-
-The LDAP database stores the user/passwords and user groups, while the `shiro.ini` file is used to map the LDAP groups to roles, and to map the roles to permissions.
-
-== Shiro Configuration
-
-To use LDAP involves telling Shiro how to instantiate the realm.  This bootstrapping info lives in the `WEB-INF/shiro.ini`:
-
-[source,ini]
-----
-contextFactory = org.apache.isis.security.shiro.IsisLdapContextFactory
-contextFactory.url = ldap://localhost:10389
-contextFactory.systemUsername = uid=admin,ou=system        # <1>
-contextFactory.systemPassword = secret
-contextFactory.authenticationMechanism = CRAM-MD5          # <2>
-contextFactory.systemAuthenticationMechanism = simple
-
-ldapRealm = org.apache.isis.security.shiro.IsisLdapRealm   # <3>
-ldapRealm.contextFactory = $contextFactory
-
-ldapRealm.searchBase = ou=groups,o=mojo                    # <4>
-ldapRealm.groupObjectClass = groupOfUniqueNames            # <5>
-ldapRealm.uniqueMemberAttribute = uniqueMember             # <6>
-ldapRealm.uniqueMemberAttributeValueTemplate = uid={0}
-
-# optional mapping from physical groups to logical application roles
-ldapRealm.rolesByGroup = \                                 # <7>
-    LDN_USERS: user_role,\
-    NYK_USERS: user_role,\
-    HKG_USERS: user_role,\
-    GLOBAL_ADMIN: admin_role,\
-    DEMOS: self-install_role
-
-ldapRealm.permissionsByRole=\                              # <8>
-   user_role = *:ToDoItemsJdo:*:*,\
-               *:ToDoItem:*:*; \
-   self-install_role = *:ToDoItemsFixturesService:install:* ; \
-   admin_role = *
-
-securityManager.realms = $ldapRealm
-----
-<1> user accounts are searched using a dedicated service account
-<2> SASL (CRAM-MD5) authentication is used for this authentication
-<3> Apache Isis' implementation of the LDAP realm.
-<4> groups are searched under `ou=groups,o=mojo` (where `mojo` is the company name)
-<5> each group has an LDAP objectClass of `groupOfUniqueNames`
-<6> each group has a vector attribute of `uniqueMember`
-<7> groups looked up from LDAP can optionally be mapped to logical roles; otherwise groups are used as role names directly
-<8> roles are mapped in turn to permissions
-
-The value of `uniqueMember` is in the form `uid=xxx`, with `xxx` being the uid of the user
-* users searched under `ou=system`
-* users have, at minimum, a `uid` attribute and a password
-* the users credentials are used to verify their user/password
-
-The above configuration has been tested against http://directory.apache.org/apacheds/[ApacheDS], v1.5.7. This can be administered using http://directory.apache.org/studio/[Apache Directory Studio], v1.5.3.
-
-
-[TIP]
-.Shiro Realm Mappings
-====
-When configuring role based permission mapping, there can only be one of these entries per realm:
-
-[source,ini]
-----
-realm.groupToRolesMappings = ...
-----
-
-and
-
-[source,ini]
-----
-realm.roleToPermissionsMappings = ...
-----
-
-This forces you to put everything on one line for each of the above.  This is, unfortunately, a Shiro "feature".  And if you repeat the entries above then it's "last one wins".)
-
-To make the configuration maintainable, use "\" to separate the mappings onto separate lines in the file.  Use this technique for both group to roles mapping and role to permission mapping. If you use the '&#39; after the "," that separates the key:value pairs it is more readable.
-====
-
-
-
-
-
-
-== Externalizing role perms
-
-As an alternative to injecting the `permissionsByRole` property, the role/permission mapping can alternatively be specified by injecting a resource path:
-
-[source,ini]
-----
-ldapRealm.resourcePath=classpath:webapp/myroles.ini
-----
-
-where `myroles.ini` is in `src/main/resources/webapp`, and takes the form:
-
-[source,ini]
-----
-[roles]
-user_role = *:ToDoItemsJdo:*:*,\
-            *:ToDoItem:*:*
-self-install_role = *:ToDoItemsFixturesService:install:*
-admin_role = *
-----
-
-This separation of the role/mapping can be useful if Shiro is configured to support multiple realms (eg an LdapRealm based one and also an TextRealm)
-
-
-
-
-== Active DS LDAP tutorial
-
-The screenshots below show how to setup LDAP accounts in ApacheDS using the Apache Directory Studio.
-
-The setup here was initially based on http://krams915.blogspot.co.uk/2011/01/ldap-apache-directory-studio-basic.html[this tutorial], however we have moved the user accounts so that they are defined in a separate LDAP node.
-
-To start, create a partition in order to hold the mojo node (holding the groups):
-
-image::{_imagesdir}/configuration/configuring-shiro/ldap/activeds-ldap-mojo-partition.png[ActiveDS LDAP Users]
-
-Create the `ou=groups,o=mojo` hierarchy:
-
-image::{_imagesdir}/configuration/configuring-shiro/ldap/activeds-ldap-mojo-root-dse.png[ActiveDS LDAP Users]
-
-Configure SASL authentication. This means that the checking of user/password is done implicitly by virtue of Apache Isis connecting to LDAP using these credentials:
-
-image::{_imagesdir}/configuration/configuring-shiro/ldap/activeds-ldap-sasl-authentication.png[ActiveDS LDAP Users]
-
-In order for SASL to work, it seems to be necessary to put users under `o=system`. (This is why the setup is slightly different than the tutorial mentioned above):
-
-image::{_imagesdir}/configuration/configuring-shiro/ldap/activeds-ldap-users.png[ActiveDS LDAP Users]
-
-Configure the users into the groups:
-
-image::{_imagesdir}/configuration/configuring-shiro/ldap/activeds-ldap-groups.png[ActiveDS LDAP Users]
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/45db638e/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-isisaddons-security-module-realm.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-isisaddons-security-module-realm.adoc b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-isisaddons-security-module-realm.adoc
deleted file mode 100644
index e81a06a..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-isisaddons-security-module-realm.adoc
+++ /dev/null
@@ -1,36 +0,0 @@
-[[_ugsec_shiro-isisaddons-security-module-realm]]
-= 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/
-
-
-
-The https://github.com/isisaddons/isis-module-security[Isis Addons' security module] (not ASF) provides a complete
-security subdomain for users, roles, permissions; all are persisted as domain entities.
-
-What that means, of course, that they can also be administered through your Isis application.  Moreover, the set of permissions (to features) is derived completely from your application's metamodel; in essence the permissions are "type-safe".  
-
-
-In order to play along, the module includes a Shiro realm, which fits in as follows:
-
-The general configuration is as follows:
-
-image::{_imagesdir}security/security-apis-impl/configure-shiro-to-use-isisaddons-security-module-realm.PNG[width="600px"]
-
-where the `IsisModuleSecurityRealm` realm is the implementation provided by the module.
-
-In the configuration above user passwords are stored in the database.  The module uses link:http://www.mindrot.org/projects/jBCrypt/[jBCrypt] so that passwords are only stored in a (one-way) encrypted form in the database.
-
-
-
-The security module also supports a slightly more sophisticated configuration.  Most organizations use LDAP for user credentials, and maintaining two separate user accounts would be less than ideal.  The `IsisModuleSecurityRealm` can therefore be configured with a subsidiary "delegate" realm that is responsible for performing the primary authentication of the user; if that passes then a user is created (as a domain entity) automatically.
-In most cases this delegate realm will be the LDAP realm, and so the architecture becomes:
-
-image::{_imagesdir}security/security-apis-impl/configure-shiro-to-use-isisaddons-security-module-realm-with-delegate-realm.PNG[width="600px"]
-
-
-The security module has many more features than are described here, all of which are described in the module's link:https://github.com/isisaddons/isis-module-security[README].  The README also explains in detail how to configure an existing app to use this module.
-
-You can also look at the Isisaddons https://github.com/isisaddons/isis-app-todoapp[todoapp example] (not ASF), which is preconfigured to use the security module.
-

http://git-wip-us.apache.org/repos/asf/isis/blob/45db638e/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-jdbc-realm.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-jdbc-realm.adoc b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-jdbc-realm.adoc
deleted file mode 100644
index b16edf2..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-jdbc-realm.adoc
+++ /dev/null
@@ -1,113 +0,0 @@
-[[_ugsec_shiro-jdbc-realm]]
-= 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/
-
-
-
-There is nothing to stop you from using some other `Realm` implementation (or indeed writing one yourself).  For example, you could use Shiro's own JDBC realm that loads user/password details from a database.
-
-[WARNING]
-====
-If you are happy to use a database then we strongly recommend you use the http://github.com/isisaddons/isis-module-security[Isis addons' security] module instead of a vanilla JDBC; it is far more sophisticated and moreover gives you the ability to administer the system from within your Isis application.
-====
-
-If you go down this route, then the architecture is as follows:
-
-image::{_imagesdir}security/security-apis-impl/configure-shiro-to-use-custom-jdbc-realm.png[width="600px"]
-
-
-
-
-There's quite a lot of configuration required (in `WEB-INF/shiro.ini`) to set up a JDBC realm, so we'll break it out into sections.
-
-First, we need to set up the connection to JDBC:
-
-[source,ini]
-----
-jdbcRealm=org.apache.shiro.realm.jdbc.JdbcRealm        # <1>
-
-jof = org.apache.shiro.jndi.JndiObjectFactory          # <2>
-jof.resourceName = jdbc/postgres                       # <3>
-jof.requiredType = javax.sql.DataSource
-jof.resourceRef = true
-
-jdbcRealm.dataSource = $jof                            # <4>
-----
-<1> instantiate the JDBC realm
-<2> instantiate factory object to lookup DataSource from servlet container
-<3> name of the datasource (as configured in `web.xml`)
-<4> instruct JDBC realm to obtain datasource from the JNDI
-
-
-We next need to tell the realm how to query the database.  Shiro supports any schema; what matters is the input search argument and the output results.
-
-[source,ini]
-----
-
-jdbcRealm.authenticationQuery =         \              # <1>
-        select password                 \
-          from users                    \
-         where username = ?
-
-jdbcRealm.userRolesQuery =              \              # <2>
-        select r.label                  \
-          from users_roles ur           \
-    inner join roles r                  \
-            on ur.role_id = r.id        \
-         where user_id = (              \
-            select id                   \
-             from users                 \
-            where username = ?);        \
-
-jdbcRealm.permissionsQuery=             \               # <3>
-        select p.permission             \
-          from roles_permissions rp     \
-    inner join permissions p            \
-            on rp.permission_id = p.id  \
-         where rp.role_id = (           \
-            select id                   \
-             from roles                 \
-            where label = ?);
-
-jdbcRealm.permissionsLookupEnabled=true                 # <4>
-----
-<1> query to find password for user
-<2> query to find roles for user
-<3> query to find permissions for role
-<4> enable permissions lookup
-
-[WARNING]
-====
-The `permissionsLookupEnabled` is very important, otherwise Shiro just returns an empty list of permissions and your users will have no access to any features(!).
-====
-
-We also should ensure that the passwords are not stored as plain-text:
-
-[source,ini]
-----
-dps = org.apache.shiro.authc.credential.DefaultPasswordService   # <1>
-pm = org.apache.shiro.authc.credential.PasswordMatcher           # <2>
-pm.passwordService = $dps
-jdbcRealm.credentialsMatcher = $pm                               # <3>
-----
-<1> mechanism to encrypts password
-<2> service to match passwords
-<3> instruct JDBC realm to use password matching service when authenticating
-
-
-And finally we need to tell Shiro to use the realm, in the usual fashion:
-
-[source,ini]
-----
-securityManager.realms = $jdbcRealm
-----
-
-Using the above configuration you will also need to setup a `DataSource`.  The details vary by servlet container, for example this is link:https://tomcat.apache.org/tomcat-8.0-doc/jndi-datasource-examples-howto.html[how to do the setup on Tomcat 8.0].
-
-[WARNING]
-====
-The name of the `DataSource` can also vary by servlet container; see for example link:http://stackoverflow.com/questions/17441019/how-to-configure-jdbcrealm-to-obtain-its-datasource-from-jndi/23784702#23784702[this StackOverflow answer].
-====
-

http://git-wip-us.apache.org/repos/asf/isis/blob/45db638e/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations.adoc b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations.adoc
new file mode 100644
index 0000000..df8b0a6
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations.adoc
@@ -0,0 +1,15 @@
+[[_ugsec_shiro-realm-implementations]]
+= Shiro Realm Implementations
+: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/
+
+
+
+include::_ugsec_shiro-realm-implementations_ini-realm.adoc[leveloffset=+1]
+
+include::_ugsec_shiro-realm-implementations_isis-ldap-realm.adoc[leveloffset=+1]
+
+include::_ugsec_shiro-realm-implementations_isisaddons-security-module-realm.adoc[leveloffset=+1]
+
+include::_ugsec_shiro-realm-implementations_jdbc-realm.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/45db638e/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_ini-realm.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_ini-realm.adoc b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_ini-realm.adoc
new file mode 100644
index 0000000..d72defc
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_ini-realm.adoc
@@ -0,0 +1,133 @@
+[[_ugsec_shiro-realm-implementations_ini-realm]]
+= 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/
+
+
+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:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] is configured to use this realm.
+
+The diagram below shows the Isis and components involved:
+
+image::{_imagesdir}security/security-apis-impl/configure-shiro-to-use-ini-realm.PNG[width="600px"]
+
+The realm is responsible for validating the user credentials, and then creates a Shiro link:http://shiro.apache.org/static/latest/apidocs/org/apache/shiro/subject/Subject.html[`Subject`] which represents the user (for the current request).  Apache Isis `Authenticator` component then interacts with the `Subject` in order to check permissions.
+
+
+
+
+== Shiro Configuration
+
+To use the built-in `IniRealm`, we add the following to `WEB-INF/shiro.ini`:
+
+[source,ini]
+----
+securityManager.realms = $iniRealm
+----
+
+(Unlike other realms) there is no need to "define" `$iniRealm`; it is automatically available to us.
+
+Specifying `$iniRealm` means that the usernames/passwords, roles and permissions are read from the `shiro.ini` file itself.  Specifically:
+
+* the users/passwords and their roles from the `[users]` sections;
+* the roles are mapped to permissions in the `[roles]` section.
+
+The format of these is described below.
+
+=== `[users]` section
+
+This section lists users, passwords and their roles.
+
+For example:
+
+[source,ini]
+----
+sven = pass, admin_role
+dick = pass, user_role, analysis_role, self-install_role
+bob  = pass, user_role, self-install_role
+----
+The first value is the password (eg "pass", the remaining values are the role(s).
+
+
+=== `[roles]` section
+
+This section lists roles and their corresponding permissions.
+
+For example:
+
+[source,ini]
+----
+user_role = *:ToDoItems:*:*,\
+            *:ToDoItem:*:*,\
+            *:ToDoAppDashboard:*:*
+analysis_role = *:ToDoItemAnalysis:*:*,\
+            *:ToDoItemsByCategoryViewModel:*:*,\
+            *:ToDoItemsByDateRangeViewModel:*:*
+self-install_role = *:ToDoItemsFixturesService:install:*
+admin_role = *
+----
+
+The value is a comma-separated list of permissions for the role.  The format is:
+
+[source,ini]
+----
+packageName:className:memberName:r,w
+----
+
+where:
+
+* `memberName` is the property, collection or action name.
+* `r` indicates that the member is visible
+* `w` indicates that the member is usable (editable or invokable)
+
+and where each of the parts of the permission string can be wildcarded using `*`.
+
+Because these are wildcards, a '*' can be used at any level. Additionally, missing levels assume wildcards.
+
+Thus:
+
+[source,ini]
+----
+com.mycompany.myapp:Customer:firstName:r,w   # view or edit customer's firstName
+com.mycompany.myapp:Customer:lastName:r      # view customer's lastName only
+com.mycompany.myapp:Customer:placeOrder:*    # view and invoke placeOrder action
+com.mycompany.myapp:Customer:placeOrder      # ditto
+com.mycompany.myapp:Customer:*:r             # view all customer class members
+com.mycompany.myapp:*:*:r                    # view-only access for all classes in myapp package
+com.mycompany.myapp:*:*:*                    # view/edit for all classes in myapp package
+com.mycompany.myapp:*:*                      # ditto
+com.mycompany.myapp:*                        # ditto
+com.mycompany.myapp                          # ditto
+*                                            # view/edit access to everything
+----
+
+[TIP]
+====
+The format of the permissions string is configurable in Shiro, and Apache Isis uses this to provide an extended wildcard format, described xref:../ugsec/ugsec.adoc#_ugsec_shiro-isis-enhanced-wildcard-permission[here].
+====
+
+
+
+
+== Externalized IniRealm
+
+There's no requirement for all users/roles to be defined in the `shiro.ini` file.  Instead, a realm can be defined that loads its users/roles from some other resource.
+
+For example:
+
+[source,ini]
+----
+$realm1=org.apache.shiro.realm.text.IniRealm # <1>
+realm1.resourcePath=classpath:webapp/realm1.ini # <2>
+----
+<1> happens to (coincidentally) be the link:http://shiro.apache.org/static/latest/apidocs/org/apache/shiro/realm/text/IniRealm.html[same implementation] as Shiro's built-in $iniRealm
+<2> in this case load the users/roles from the `src/main/resources/webapp/realm1.ini` file.
+
+Note that a URL could be provided as the `resourcePath`, so a centralized config file could be used.  Even so, the
+
+[NOTE]
+====
+If configured this way then the `[users]` and `[roles]` sections of `shiro.ini` become unused. Instead, the corresponding sections from for `realm1.ini` are used instead.
+====

http://git-wip-us.apache.org/repos/asf/isis/blob/45db638e/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_isis-ldap-realm.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_isis-ldap-realm.adoc b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_isis-ldap-realm.adoc
new file mode 100644
index 0000000..5e5a805
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_isis-ldap-realm.adoc
@@ -0,0 +1,146 @@
+[[_ugsec_shiro-realm-implementations_isis-ldap-realm]]
+= 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/
+
+
+Isis ships with an implementation of http://shiro.apache.org[Apache Shiro]'s `Realm` class that allows user authentication and authorization to be performed against an LDAP server.
+
+image::{_imagesdir}security/security-apis-impl/configure-shiro-to-use-isis-ldap-realm.PNG[width="600px"]
+
+The LDAP database stores the user/passwords and user groups, while the `shiro.ini` file is used to map the LDAP groups to roles, and to map the roles to permissions.
+
+== Shiro Configuration
+
+To use LDAP involves telling Shiro how to instantiate the realm.  This bootstrapping info lives in the `WEB-INF/shiro.ini`:
+
+[source,ini]
+----
+contextFactory = org.apache.isis.security.shiro.IsisLdapContextFactory
+contextFactory.url = ldap://localhost:10389
+contextFactory.systemUsername = uid=admin,ou=system        # <1>
+contextFactory.systemPassword = secret
+contextFactory.authenticationMechanism = CRAM-MD5          # <2>
+contextFactory.systemAuthenticationMechanism = simple
+
+ldapRealm = org.apache.isis.security.shiro.IsisLdapRealm   # <3>
+ldapRealm.contextFactory = $contextFactory
+
+ldapRealm.searchBase = ou=groups,o=mojo                    # <4>
+ldapRealm.groupObjectClass = groupOfUniqueNames            # <5>
+ldapRealm.uniqueMemberAttribute = uniqueMember             # <6>
+ldapRealm.uniqueMemberAttributeValueTemplate = uid={0}
+
+# optional mapping from physical groups to logical application roles
+ldapRealm.rolesByGroup = \                                 # <7>
+    LDN_USERS: user_role,\
+    NYK_USERS: user_role,\
+    HKG_USERS: user_role,\
+    GLOBAL_ADMIN: admin_role,\
+    DEMOS: self-install_role
+
+ldapRealm.permissionsByRole=\                              # <8>
+   user_role = *:ToDoItemsJdo:*:*,\
+               *:ToDoItem:*:*; \
+   self-install_role = *:ToDoItemsFixturesService:install:* ; \
+   admin_role = *
+
+securityManager.realms = $ldapRealm
+----
+<1> user accounts are searched using a dedicated service account
+<2> SASL (CRAM-MD5) authentication is used for this authentication
+<3> Apache Isis' implementation of the LDAP realm.
+<4> groups are searched under `ou=groups,o=mojo` (where `mojo` is the company name)
+<5> each group has an LDAP objectClass of `groupOfUniqueNames`
+<6> each group has a vector attribute of `uniqueMember`
+<7> groups looked up from LDAP can optionally be mapped to logical roles; otherwise groups are used as role names directly
+<8> roles are mapped in turn to permissions
+
+The value of `uniqueMember` is in the form `uid=xxx`, with `xxx` being the uid of the user
+* users searched under `ou=system`
+* users have, at minimum, a `uid` attribute and a password
+* the users credentials are used to verify their user/password
+
+The above configuration has been tested against http://directory.apache.org/apacheds/[ApacheDS], v1.5.7. This can be administered using http://directory.apache.org/studio/[Apache Directory Studio], v1.5.3.
+
+
+[TIP]
+.Shiro Realm Mappings
+====
+When configuring role based permission mapping, there can only be one of these entries per realm:
+
+[source,ini]
+----
+realm.groupToRolesMappings = ...
+----
+
+and
+
+[source,ini]
+----
+realm.roleToPermissionsMappings = ...
+----
+
+This forces you to put everything on one line for each of the above.  This is, unfortunately, a Shiro "feature".  And if you repeat the entries above then it's "last one wins".)
+
+To make the configuration maintainable, use "\" to separate the mappings onto separate lines in the file.  Use this technique for both group to roles mapping and role to permission mapping. If you use the '&#39; after the "," that separates the key:value pairs it is more readable.
+====
+
+
+
+
+
+
+== Externalizing role perms
+
+As an alternative to injecting the `permissionsByRole` property, the role/permission mapping can alternatively be specified by injecting a resource path:
+
+[source,ini]
+----
+ldapRealm.resourcePath=classpath:webapp/myroles.ini
+----
+
+where `myroles.ini` is in `src/main/resources/webapp`, and takes the form:
+
+[source,ini]
+----
+[roles]
+user_role = *:ToDoItemsJdo:*:*,\
+            *:ToDoItem:*:*
+self-install_role = *:ToDoItemsFixturesService:install:*
+admin_role = *
+----
+
+This separation of the role/mapping can be useful if Shiro is configured to support multiple realms (eg an LdapRealm based one and also an TextRealm)
+
+
+
+
+== Active DS LDAP tutorial
+
+The screenshots below show how to setup LDAP accounts in ApacheDS using the Apache Directory Studio.
+
+The setup here was initially based on http://krams915.blogspot.co.uk/2011/01/ldap-apache-directory-studio-basic.html[this tutorial], however we have moved the user accounts so that they are defined in a separate LDAP node.
+
+To start, create a partition in order to hold the mojo node (holding the groups):
+
+image::{_imagesdir}/configuration/configuring-shiro/ldap/activeds-ldap-mojo-partition.png[ActiveDS LDAP Users]
+
+Create the `ou=groups,o=mojo` hierarchy:
+
+image::{_imagesdir}/configuration/configuring-shiro/ldap/activeds-ldap-mojo-root-dse.png[ActiveDS LDAP Users]
+
+Configure SASL authentication. This means that the checking of user/password is done implicitly by virtue of Apache Isis connecting to LDAP using these credentials:
+
+image::{_imagesdir}/configuration/configuring-shiro/ldap/activeds-ldap-sasl-authentication.png[ActiveDS LDAP Users]
+
+In order for SASL to work, it seems to be necessary to put users under `o=system`. (This is why the setup is slightly different than the tutorial mentioned above):
+
+image::{_imagesdir}/configuration/configuring-shiro/ldap/activeds-ldap-users.png[ActiveDS LDAP Users]
+
+Configure the users into the groups:
+
+image::{_imagesdir}/configuration/configuring-shiro/ldap/activeds-ldap-groups.png[ActiveDS LDAP Users]
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/45db638e/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_isisaddons-security-module-realm.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_isisaddons-security-module-realm.adoc b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_isisaddons-security-module-realm.adoc
new file mode 100644
index 0000000..5ece3b3
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_isisaddons-security-module-realm.adoc
@@ -0,0 +1,36 @@
+[[_ugsec_shiro-realm-implementations_isisaddons-security-module-realm]]
+= 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/
+
+
+
+The https://github.com/isisaddons/isis-module-security[Isis Addons' security module] (not ASF) provides a complete
+security subdomain for users, roles, permissions; all are persisted as domain entities.
+
+What that means, of course, that they can also be administered through your Isis application.  Moreover, the set of permissions (to features) is derived completely from your application's metamodel; in essence the permissions are "type-safe".  
+
+
+In order to play along, the module includes a Shiro realm, which fits in as follows:
+
+The general configuration is as follows:
+
+image::{_imagesdir}security/security-apis-impl/configure-shiro-to-use-isisaddons-security-module-realm.PNG[width="600px"]
+
+where the `IsisModuleSecurityRealm` realm is the implementation provided by the module.
+
+In the configuration above user passwords are stored in the database.  The module uses link:http://www.mindrot.org/projects/jBCrypt/[jBCrypt] so that passwords are only stored in a (one-way) encrypted form in the database.
+
+
+
+The security module also supports a slightly more sophisticated configuration.  Most organizations use LDAP for user credentials, and maintaining two separate user accounts would be less than ideal.  The `IsisModuleSecurityRealm` can therefore be configured with a subsidiary "delegate" realm that is responsible for performing the primary authentication of the user; if that passes then a user is created (as a domain entity) automatically.
+In most cases this delegate realm will be the LDAP realm, and so the architecture becomes:
+
+image::{_imagesdir}security/security-apis-impl/configure-shiro-to-use-isisaddons-security-module-realm-with-delegate-realm.PNG[width="600px"]
+
+
+The security module has many more features than are described here, all of which are described in the module's link:https://github.com/isisaddons/isis-module-security[README].  The README also explains in detail how to configure an existing app to use this module.
+
+You can also look at the Isisaddons https://github.com/isisaddons/isis-app-todoapp[todoapp example] (not ASF), which is preconfigured to use the security module.
+

http://git-wip-us.apache.org/repos/asf/isis/blob/45db638e/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_jdbc-realm.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_jdbc-realm.adoc b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_jdbc-realm.adoc
new file mode 100644
index 0000000..fde09d1
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_jdbc-realm.adoc
@@ -0,0 +1,113 @@
+[[_ugsec_shiro-realm-implementations_jdbc-realm]]
+= 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/
+
+
+
+There is nothing to stop you from using some other `Realm` implementation (or indeed writing one yourself).  For example, you could use Shiro's own JDBC realm that loads user/password details from a database.
+
+[WARNING]
+====
+If you are happy to use a database then we strongly recommend you use the http://github.com/isisaddons/isis-module-security[Isis addons' security] module instead of a vanilla JDBC; it is far more sophisticated and moreover gives you the ability to administer the system from within your Isis application.
+====
+
+If you go down this route, then the architecture is as follows:
+
+image::{_imagesdir}security/security-apis-impl/configure-shiro-to-use-custom-jdbc-realm.png[width="600px"]
+
+
+
+
+There's quite a lot of configuration required (in `WEB-INF/shiro.ini`) to set up a JDBC realm, so we'll break it out into sections.
+
+First, we need to set up the connection to JDBC:
+
+[source,ini]
+----
+jdbcRealm=org.apache.shiro.realm.jdbc.JdbcRealm        # <1>
+
+jof = org.apache.shiro.jndi.JndiObjectFactory          # <2>
+jof.resourceName = jdbc/postgres                       # <3>
+jof.requiredType = javax.sql.DataSource
+jof.resourceRef = true
+
+jdbcRealm.dataSource = $jof                            # <4>
+----
+<1> instantiate the JDBC realm
+<2> instantiate factory object to lookup DataSource from servlet container
+<3> name of the datasource (as configured in `web.xml`)
+<4> instruct JDBC realm to obtain datasource from the JNDI
+
+
+We next need to tell the realm how to query the database.  Shiro supports any schema; what matters is the input search argument and the output results.
+
+[source,ini]
+----
+
+jdbcRealm.authenticationQuery =         \              # <1>
+        select password                 \
+          from users                    \
+         where username = ?
+
+jdbcRealm.userRolesQuery =              \              # <2>
+        select r.label                  \
+          from users_roles ur           \
+    inner join roles r                  \
+            on ur.role_id = r.id        \
+         where user_id = (              \
+            select id                   \
+             from users                 \
+            where username = ?);        \
+
+jdbcRealm.permissionsQuery=             \               # <3>
+        select p.permission             \
+          from roles_permissions rp     \
+    inner join permissions p            \
+            on rp.permission_id = p.id  \
+         where rp.role_id = (           \
+            select id                   \
+             from roles                 \
+            where label = ?);
+
+jdbcRealm.permissionsLookupEnabled=true                 # <4>
+----
+<1> query to find password for user
+<2> query to find roles for user
+<3> query to find permissions for role
+<4> enable permissions lookup
+
+[WARNING]
+====
+The `permissionsLookupEnabled` is very important, otherwise Shiro just returns an empty list of permissions and your users will have no access to any features(!).
+====
+
+We also should ensure that the passwords are not stored as plain-text:
+
+[source,ini]
+----
+dps = org.apache.shiro.authc.credential.DefaultPasswordService   # <1>
+pm = org.apache.shiro.authc.credential.PasswordMatcher           # <2>
+pm.passwordService = $dps
+jdbcRealm.credentialsMatcher = $pm                               # <3>
+----
+<1> mechanism to encrypts password
+<2> service to match passwords
+<3> instruct JDBC realm to use password matching service when authenticating
+
+
+And finally we need to tell Shiro to use the realm, in the usual fashion:
+
+[source,ini]
+----
+securityManager.realms = $jdbcRealm
+----
+
+Using the above configuration you will also need to setup a `DataSource`.  The details vary by servlet container, for example this is link:https://tomcat.apache.org/tomcat-8.0-doc/jndi-datasource-examples-howto.html[how to do the setup on Tomcat 8.0].
+
+[WARNING]
+====
+The name of the `DataSource` can also vary by servlet container; see for example link:http://stackoverflow.com/questions/17441019/how-to-configure-jdbcrealm-to-obtain-its-datasource-from-jndi/23784702#23784702[this StackOverflow answer].
+====
+

http://git-wip-us.apache.org/repos/asf/isis/blob/45db638e/adocs/documentation/src/main/asciidoc/guides/ugsec/ugsec.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugsec/ugsec.adoc b/adocs/documentation/src/main/asciidoc/guides/ugsec/ugsec.adoc
index 449abb5..8b5ca61 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugsec/ugsec.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugsec/ugsec.adoc
@@ -82,13 +82,9 @@ xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`] used to c
 
 include::_ugsec_configuring-isis-to-use-shiro.adoc[leveloffset=+1]
 
-include::_ugsec_shiro-ini-realm.adoc[leveloffset=+1]
+include::_ugsec_shiro-realm-implementations.adoc[leveloffset=+1]
 
-include::_ugsec_shiro-isis-ldap-realm.adoc[leveloffset=+1]
 
-include::_ugsec_shiro-isisaddons-security-module-realm.adoc[leveloffset=+1]
-
-include::_ugsec_shiro-jdbc-realm.adoc[leveloffset=+1]
 
 include::_ugsec_shiro-isis-enhanced-wildcard-permission.adoc[leveloffset=+1]
 

http://git-wip-us.apache.org/repos/asf/isis/blob/45db638e/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips.adoc
index fa9b85f..d83beb4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips.adoc
@@ -9,7 +9,7 @@ This chapter provides some solutions for problems we've encountered ourselves or
 
 See also hints-n-tips chapters in the:
 
-* the xref:../dg/dg.adoc#_ugvw_hints-and-tips[Developers'] guide
+* the xref:../dg/dg.adoc#_dg_hints-and-tips[Developers'] guide
 
 * the xref:../ugvw/ugvw.adoc#_ugvw_hints-and-tips[Wicket viewer] guide
 

http://git-wip-us.apache.org/repos/asf/isis/blob/45db638e/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_hints-and-tips.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_hints-and-tips.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_hints-and-tips.adoc
index 8b7282b..0730daa 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_hints-and-tips.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_hints-and-tips.adoc
@@ -10,7 +10,7 @@ This chapter provides some solutions for problems we've encountered ourselves or
 
 See also hints-n-tips chapters in the:
 
-* the xref:../dg/dg.adoc#_ugvw_hints-and-tips[Developers'] guide
+* the xref:../dg/dg.adoc#_dg_hints-and-tips[Developers'] guide
 
 * the xref:../ugvw/ugvw.adoc#_ugvw_hints-and-tips[Wicket viewer] guide (this chapter)
 

[40/58] [abbrv] isis git commit: ISIS-1521: fixes xref links between pages and guides

[da...@apache.org]

ISIS-1521: fixes xref links between pages and guides


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/4807f4c2
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/4807f4c2
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/4807f4c2

Branch: refs/heads/wip
Commit: 4807f4c2ee537a039308bcc09611a7a8983a0ae6
Parents: b2b87ca
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Fri Apr 14 15:37:29 2017 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Thu Apr 20 09:09:30 2017 +0100

----------------------------------------------------------------------
 .../_migration-notes_1.13.0-to-1.14.0.adoc      |   2 +-
 .../_migration-notes_1.14.0-to-1.15.0.adoc      |   2 +-
 .../pages/how-isis-works/how-isis-works.adoc    |   2 +-
 .../_powered-by_gesconsultor-grc.adoc           |   6 +-
 .../main/asciidoc/pages/tg/_tg_pet-clinic.adoc  |   4 +-
 .../tg/_tg_stop-scaffolding-start-coding.adoc   | 136 +++++++++----------
 .../release-notes/_release-notes_1.9.0.adoc     |   2 +-
 7 files changed, 77 insertions(+), 77 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/4807f4c2/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.13.0-to-1.14.0.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.13.0-to-1.14.0.adoc b/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.13.0-to-1.14.0.adoc
index f36cfcf..6f3b756 100644
--- a/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.13.0-to-1.14.0.adoc
+++ b/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.13.0-to-1.14.0.adoc
@@ -32,7 +32,7 @@ This is disabled by default; if enabled, this configuration property will treat
 
 * `isis.reflector.validator.noParamsOnly` +
 +
-When searching for  xref:rgcms.adoc#_rgcms_methods_prefixes_disable[`disableXxx()`] or xref:rgcms.adoc#_rgcms_methods_prefixes_hide[`hideXxx()`] supporting methods, whether to search only for the no-param version (or also for supporting methods that match the parameter types of the action). +
+When searching for  xref:../guides/rgcms/rgcms.adoc#_rgcms_methods_prefixes_disable[`disableXxx()`] or xref:../guides/rgcms/rgcms.adoc#_rgcms_methods_prefixes_hide[`hideXxx()`] supporting methods, whether to search only for the no-param version (or also for supporting methods that match the parameter types of the action). +
 +
 This is disabled by default; if enabled then this makes for a simpler programming model.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/4807f4c2/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.14.0-to-1.15.0.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.14.0-to-1.15.0.adoc b/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.14.0-to-1.15.0.adoc
index 5a151f2..703d61f 100644
--- a/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.14.0-to-1.15.0.adoc
+++ b/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.14.0-to-1.15.0.adoc
@@ -8,7 +8,7 @@
 
 == Rename of isis-viewer-wicket artifacts
 
-The `<groupId>` and `<artifactId>` of the xref:ugvw.adoc#[Wicket viewer] have been made consistent with other artifacts:
+The `<groupId>` and `<artifactId>` of the xref:../guides/ugvw/ugvw.adoc#[Wicket viewer] have been made consistent with other artifacts:
 
 * the `<groupId>` has been changed from `org.apache.isis.viewer` to `org.apache.isis.core`
 * the `<artifactId>` has been changed from `isis-viewer-wicket-???` to `isis-core-viewer-wicket-???`

http://git-wip-us.apache.org/repos/asf/isis/blob/4807f4c2/adocs/documentation/src/main/asciidoc/pages/how-isis-works/how-isis-works.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/pages/how-isis-works/how-isis-works.adoc b/adocs/documentation/src/main/asciidoc/pages/how-isis-works/how-isis-works.adoc
index 53061d1..5684361 100644
--- a/adocs/documentation/src/main/asciidoc/pages/how-isis-works/how-isis-works.adoc
+++ b/adocs/documentation/src/main/asciidoc/pages/how-isis-works/how-isis-works.adoc
@@ -13,6 +13,6 @@ video::ludOLyi6VyY[youtube,width="840px",height="630px"]
 
 [NOTE]
 ====
-Note that this screencast shows an earlier version of the xref:ugvw.adoc#[Wicket viewer] UI (specifically, pre 1.8.0).
+Note that this screencast shows an earlier version of the xref:../../guides/ugvw/ugvw.adoc#[Wicket viewer] UI (specifically, pre 1.8.0).
 ====
 

http://git-wip-us.apache.org/repos/asf/isis/blob/4807f4c2/adocs/documentation/src/main/asciidoc/pages/powered-by/_powered-by_gesconsultor-grc.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/pages/powered-by/_powered-by_gesconsultor-grc.adoc b/adocs/documentation/src/main/asciidoc/pages/powered-by/_powered-by_gesconsultor-grc.adoc
index fae46d0..32f40c8 100644
--- a/adocs/documentation/src/main/asciidoc/pages/powered-by/_powered-by_gesconsultor-grc.adoc
+++ b/adocs/documentation/src/main/asciidoc/pages/powered-by/_powered-by_gesconsultor-grc.adoc
@@ -82,16 +82,16 @@ various Wavemaker services.
 
 Even so, while GRC does (as the figures above show) include custom views, the majority of the views exposed by GRC are
 automatically generated from the underlying domain entities; the GRC viewer is a proprietary version of Isis' own
-xref:ugvw.adoc#[Wicket viewer].  At the last count more than 400 domain entities, across 6 different
+xref:../../guides/ugvw/ugvw.adoc#[Wicket viewer].  At the last count more than 400 domain entities, across 6 different
 Bounded Contexts, are surfaced in the UI in this this way.
 
-At the Domain level, we also extensively use the xref:ugbtb.adoc#_ugbtb_decoupling_event-bus[domain events]
+At the Domain level, we also extensively use the xref:../../guides/ugbtb/ugbtb.adoc#_ugbtb_decoupling_event-bus[domain events]
 functionality available in Apache Isis, along with many of the (non-ASF) link:http://isisaddons.org[Isis Addons] (such
 as http://github.com/isisaddons/isis-module-audit[audit], http://github.com/isisaddons/isis-module-security[security]
 and the http://github.com/isisaddons/isis-module-excel[excel] modules).
 
 The GRC platform currently has more than 5600 automated tests, about 2000 being
-xref:ugtst.adoc#_ugtst_bdd-spec-support[BDD tests] and 3600 xref:ugtst.adoc#_ugtst_integ-test-support[integration
+xref:../../guides/ugtst/ugtst.adoc#_ugtst_bdd-spec-support[BDD tests] and 3600 xref:../../guides/ugtst/ugtst.adoc#_ugtst_integ-test-support[integration
 tests], all leveraging Apache Isis' extensive testing capabilities.
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/4807f4c2/adocs/documentation/src/main/asciidoc/pages/tg/_tg_pet-clinic.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/pages/tg/_tg_pet-clinic.adoc b/adocs/documentation/src/main/asciidoc/pages/tg/_tg_pet-clinic.adoc
index a8c6f5c..9524be4 100644
--- a/adocs/documentation/src/main/asciidoc/pages/tg/_tg_pet-clinic.adoc
+++ b/adocs/documentation/src/main/asciidoc/pages/tg/_tg_pet-clinic.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-This is a step-by-step tutorial to build up a simple "petclinic" application, starting from the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
+This is a step-by-step tutorial to build up a simple "petclinic" application, starting from the xref:../../guides/ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
 It was originally written by Jeroen van der Wal.
 
 It consists of just three domain classes (http://yuml.me/edit/3db2078c[http://yuml.me/3db2078c]):
@@ -162,7 +162,7 @@ Go back to the splash screen, and quit the app. Note that the database runs in-m
 
 == Dev environment
 
-Set up xref:dg.adoc#_dg_ide[an IDE] and import the project to be able to run and debug the app.
+Set up xref:../../guides/dg/dg.adoc#_dg_ide[an IDE] and import the project to be able to run and debug the app.
 
 Then set up a launch configuration so that you can run the app from within the IDE. To save having to run the fixtures
 every time, specify the following system properties:

http://git-wip-us.apache.org/repos/asf/isis/blob/4807f4c2/adocs/documentation/src/main/asciidoc/pages/tg/_tg_stop-scaffolding-start-coding.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/pages/tg/_tg_stop-scaffolding-start-coding.adoc b/adocs/documentation/src/main/asciidoc/pages/tg/_tg_stop-scaffolding-start-coding.adoc
index 894e0b3..f8dcbb1 100644
--- a/adocs/documentation/src/main/asciidoc/pages/tg/_tg_stop-scaffolding-start-coding.adoc
+++ b/adocs/documentation/src/main/asciidoc/pages/tg/_tg_stop-scaffolding-start-coding.adoc
@@ -94,13 +94,13 @@ Go back to the splash screen, and quit the app. Note that the database runs in-m
 
 == Dev environment
 
-Set up xref:dg.adoc#_dg_ide[an IDE] and import the project to be able to run and debug the app.
+Set up xref:../../guides/dg/dg.adoc#_dg_ide[an IDE] and import the project to be able to run and debug the app.
 
 Then set up a launch configuration and check that you can:
 
 * Run the app from within the IDE
 * Run the app in debug mode
-* Run with different deploymentTypes; note whether prototype actions (those annotated xref:rgant.adoc#_rgant-Action_restrictTo[`@Action(restrictTo=PROTOTYPING`]) are available or not:
+* Run with different deploymentTypes; note whether prototype actions (those annotated xref:../../guides/rgant/rgant.adoc#_rgant-Action_restrictTo[`@Action(restrictTo=PROTOTYPING`]) are available or not:
 * `--type SERVER_PROTOTYPE`
 * `--type SERVER`
 
@@ -206,9 +206,9 @@ Most domain objects in Apache Isis applications are persistent entities. In the
 ** eg rename to `Pet`
 * if required, rename the `SimpleObject` class' `name` property
 ** for `Pet`, can leave `name` property as is
-* specify a xref:ugfun.adoc#_ugfun_how-tos_ui-hints_object-titles-and-icons[title]
-* specify an xref:ugfun.adoc#_ugfun_how-tos_ui-hints_object-titles-and-icons[icon]
-* make the entity bookmarkable by adding the xref:rgant.adoc#_rgant-DomainObjectLayout_bookmarking[`@DomainObjectLayout#bookmarking()`] attribute.
+* specify a xref:../../guides/ugfun/ugfun.adoc#_ugfun_how-tos_ui-hints_object-titles-and-icons[title]
+* specify an xref:../../guides/ugfun/ugfun.adoc#_ugfun_how-tos_ui-hints_object-titles-and-icons[icon]
+* make the entity bookmarkable by adding the xref:../../guides/rgant/rgant.adoc#_rgant-DomainObjectLayout_bookmarking[`@DomainObjectLayout#bookmarking()`] attribute.
 * confirm is available from bookmark panel (top-left of Wicket UI)
 
 
@@ -223,15 +223,15 @@ In the simpleapp archetype the `SimpleObjects` service is a factory/repository f
 * rename the `SimpleObjects` class
 ** eg rename to `Pets`
 * review `create` action (acting as a factory)
-** as per the docs describing xref:ugfun.adoc#_ugfun_how-tos_crud[how to create or delete objects]
+** as per the docs describing xref:../../guides/ugfun/ugfun.adoc#_ugfun_how-tos_crud[how to create or delete objects]
 * rename if you wish
 ** eg `newPet(...)` or `addPet(...)`
 * review `listAll` action (acting as a repository)
-* as per the docs describing xref:ugfun.adoc#_ugfun_how-tos_crud[how to write a custom repository]
+* as per the docs describing xref:../../guides/ugfun/ugfun.adoc#_ugfun_how-tos_crud[how to write a custom repository]
 * note the annotations on the corresponding domain class (originally called `SimpleObject`, though renamed by now, eg to `Pet`)
 * rename if you wish
 ** eg `listPets()`
-* note the xref:rgant.adoc#_rgant-DomainService[`@DomainService`] annotation
+* note the xref:../../guides/rgant/rgant.adoc#_rgant-DomainService[`@DomainService`] annotation
 * optional: add an action to a return subset of objects
 ** use the JDO `@Query` annotation
 ** see for example the Isisaddons example https://github.com/isisaddons/isis-app-todoapp[todoapp] (not ASF), see https://github.com/apache/isis/blob/b3e936c9aae28754fb46c2df52b1cb9b023f9ab8/example/application/todoapp/dom/src/main/java/dom/todo/ToDoItem.java#L93[here] and https://github.com/apache/isis/blob/b3e936c9aae28754fb46c2df52b1cb9b023f9ab8/example/application/todoapp/dom/src/main/java/dom/todo/ToDoItems.java#L63[here]
@@ -245,7 +245,7 @@ Fixture scripts are used to setup the app into a known state. They are great for
 
 * rename the `SimpleObjectsTearDownFixture` class
 * and update to delete from the appropriate underlying database table(s)
-* use the injected xref:rgsvc.adoc#_rgsvc_api_IsisJdoSupport[`IsisJdoSupport`] domain service.
+* use the injected xref:../../guides/rgsvc/rgsvc.adoc#_rgsvc_api_IsisJdoSupport[`IsisJdoSupport`] domain service.
 * refactor/rename the fixture script classes that create instances your entity:
 * `RecreateSimpleObjects`, which sets up a set of objects for a given scenario
 * `SimpleObjectCreate` which creates a single object
@@ -259,9 +259,9 @@ Fixture scripts are used to setup the app into a known state. They are great for
 Most business functionality is implemented using actions basically a `public` method accepting domain classes and primitives as its parameter types. The action can return a domain entity, or a collection of entities, or a primitive/String/value, or void. If a domain entity is returned then that object is rendered immediately; if a collection is returned then the Wicket viewer renders a table. Such collections are sometimes called "standalone" collections.
 
 * write an action to update the domain property (originally called `SimpleObject#name`, though renamed by now)
-* use the xref:rgant.adoc#_rgant-ParameterLayout_named[`@ParameterLayout(named=...)`] annotation to specify the name of action parameters
-* use the xref:rgant.adoc#_rgant-Action_semantics[`@Action(semanticsOf=...)`]  annotation to indicate the semantics of the action (safe/query-only, idempotent or non-idempotent)
-* annotate safe action as bookmarkable using xref:rgant.adoc#_rgant-ActionLayout_bookmarking[`@ActionLayout(bookmarking=...)`]
+* use the xref:../../guides/rgant/rgant.adoc#_rgant-ParameterLayout_named[`@ParameterLayout(named=...)`] annotation to specify the name of action parameters
+* use the xref:../../guides/rgant/rgant.adoc#_rgant-Action_semantics[`@Action(semanticsOf=...)`]  annotation to indicate the semantics of the action (safe/query-only, idempotent or non-idempotent)
+* annotate safe action as bookmarkable using xref:../../guides/rgant/rgant.adoc#_rgant-ActionLayout_bookmarking[`@ActionLayout(bookmarking=...)`]
 * confirm is available from bookmark panel (top-left of Wicket UI)
 * optional: add an action to clone an object
 
@@ -289,7 +289,7 @@ As well as exposing the Wicket viewer, Isis also exposes a REST API (an implemen
 
 The semantics of an action (whether it is safe/query only, whether it is idempotent, whether it is neither) can be specified for each action; if not specified then Isis assumes non-idempotent. In the Wicket viewer this matters in that only query-only actions can be bookmarked or used as contributed properties/collections. In the RESTful viewer this matters in that it determines the HTTP verb (GET, PUT or POST) that is used to invoke the action.
 
-* experiment changing xref:rgant.adoc#_rgant-Action_semantics[`@Action(semantics=...)`] on actions
+* experiment changing xref:../../guides/rgant/rgant.adoc#_rgant-Action_semantics[`@Action(semantics=...)`] on actions
 * note the HTTP methods exposed in the REST API change
 * note whether the non-safe actions are bookmarkable (assuming that it has been annotated with `@ActionLayout(bookmarking=...)`, that is).
 
@@ -300,22 +300,22 @@ The semantics of an action (whether it is safe/query only, whether it is idempot
 
 Domain entities have state: either values (primitives, strings) or references to other entities. In this section we explore adding some value properties
 
-* add some xref:ugfun.adoc#_ugfun_how-tos_class-structure_properties[value properties]; also:
+* add some xref:../../guides/ugfun/ugfun.adoc#_ugfun_how-tos_class-structure_properties[value properties]; also:
 * for string properties
-** use the xref:rgant.adoc#_rgant-PropertyLayout_multiLine[`@PropertyLayout(multiLine=...)`] annotation to render a text area instead of a text box
-** use the xref:rgant.adoc#_rgant-Property_maxLength[`@Property(maxLength=...)`] annotation to specify the maximum number of characters allowable
+** use the xref:../../guides/rgant/rgant.adoc#_rgant-PropertyLayout_multiLine[`@PropertyLayout(multiLine=...)`] annotation to render a text area instead of a text box
+** use the xref:../../guides/rgant/rgant.adoc#_rgant-Property_maxLength[`@Property(maxLength=...)`] annotation to specify the maximum number of characters allowable
 ** use joda date/time properties, bigdecimals and blob/clob properties
-* use the xref:rgant.adoc#_rgant-Property_optionality[`@Column(allowsNull=...)`] annotation specify whether a property is optional or mandatory
+* use the xref:../../guides/rgant/rgant.adoc#_rgant-Property_optionality[`@Column(allowsNull=...)`] annotation specify whether a property is optional or mandatory
 * use enums for properties (eg as used in the Isis addons example https://github.com/isisaddons/isis-app-todoapp[todoapp], see https://github.com/apache/isis/blob/b3e936c9aae28754fb46c2df52b1cb9b023f9ab8/example/application/todoapp/dom/src/main/java/dom/todo/ToDoItem.java#L207[here] and https://github.com/apache/isis/blob/b3e936c9aae28754fb46c2df52b1cb9b023f9ab8/example/application/todoapp/dom/src/main/java/dom/todo/ToDoItem.java#L266[here])
 * update the corresponding domain service for creating new instances
 * for all non-optional properties will either need to prompt for a value, or calculate some suitable default
 * change the implementation of title, if need be
-* revisit the title, consider whether to use the xref:rgant.adoc#_rgant-Title[`@Title`] annotation
-** rather than the xref:rgcms.adoc#_rgcms_methods_reserved_title[`title()`] method
-* order the properties using the xref:rgant.adoc#_rgant-MemberOrder[`@MemberOrder`], also `@MemberGroupLayout`
-** see also the docs on xref:ugvw.adoc#_ugvw_layout_annotation-based[static layouts]
-* use the xref:rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`] annotation to position property/action parameter labels either to the LEFT, TOP or NONE
-** do the same for parameters using xref:rgant.adoc#_rgant-ParameterLayout[`@ParameterLayout`]
+* revisit the title, consider whether to use the xref:../../guides/rgant/rgant.adoc#_rgant-Title[`@Title`] annotation
+** rather than the xref:../../guides/rgcms/rgcms.adoc#_rgcms_methods_reserved_title[`title()`] method
+* order the properties using the xref:../../guides/rgant/rgant.adoc#_rgant-MemberOrder[`@MemberOrder`], also `@MemberGroupLayout`
+** see also the docs on xref:../../guides/ugvw/ugvw.adoc#_ugvw_layout_annotation-based[static layouts]
+* use the xref:../../guides/rgant/rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`] annotation to position property/action parameter labels either to the LEFT, TOP or NONE
+** do the same for parameters using xref:../../guides/rgant/rgant.adoc#_rgant-ParameterLayout[`@ParameterLayout`]
 
 
 
@@ -324,14 +324,14 @@ Domain entities have state: either values (primitives, strings) or references to
 
 Domain entities can also reference other domain entities. These references may be either scalar (single-valued) or vector (multi-valued). In this section we focus on scalar reference properties.
 
-* add some xref:ugfun.adoc#_ugfun_how-tos_class-structure_properties[reference properties]
+* add some xref:../../guides/ugfun/ugfun.adoc#_ugfun_how-tos_class-structure_properties[reference properties]
 * update the corresponding domain service (for creation actoin)
 * use different techniques to obtain references (shown in drop-down list box)
-** use the xref:rgant.adoc#_rgant-DomainObject_bounded[`@DomainObjectLayout(bounded=...)`] annotation on the referenced type if there are only a small number (bounded) of instances
-** use a xref:rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`] supporting method
+** use the xref:../../guides/rgant/rgant.adoc#_rgant-DomainObject_bounded[`@DomainObjectLayout(bounded=...)`] annotation on the referenced type if there are only a small number (bounded) of instances
+** use a xref:../../guides/rgcms/rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`] supporting method
 *** on a property
 *** on an action parameter
-** use a xref:rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`] supporting method
+** use a xref:../../guides/rgcms/rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`] supporting method
 *** on a property
 *** on an action parameter
 
@@ -342,7 +342,7 @@ Domain entities can also reference other domain entities. These references may b
 
 Quick detour: often we want to set up defaults to go with choices. Sensible defaults for action parameters can really improve the usability of the app.
 
-* Add xref:ugfun.adoc#_ugfun_how-tos_drop-downs-and-defaults[defaults] for action parameters
+* Add xref:../../guides/ugfun/ugfun.adoc#_ugfun_how-tos_drop-downs-and-defaults[defaults] for action parameters
 
 
 
@@ -352,12 +352,12 @@ Quick detour: often we want to set up defaults to go with choices. Sensible defa
 Returning back to references, Isis also supports vector (multi-valued) references to another object instances in other words collections. We sometimes called these "parented" collections (to distinguish from a "standalone" collection as returned from an action)
 
 * Ensure that all domain classes implement `java.lang.Comparable`
-** use the xref:rgcms.adoc#_rgcms_classes_utility_ObjectContracts[`ObjectContracts`] utility class to help implement `Comparable`
+** use the xref:../../guides/rgcms/rgcms.adoc#_rgcms_classes_utility_ObjectContracts[`ObjectContracts`] utility class to help implement `Comparable`
 *** you can also implement `equals()`, `hashCode()`, `toString()`
-* Add a xref:ugfun.adoc#_ugfun_how-tos_class-structure_collections[collection] to one of the entities
+* Add a xref:../../guides/ugfun/ugfun.adoc#_ugfun_how-tos_class-structure_collections[collection] to one of the entities
 ** Use `SortedSet` as the class
-** Use the xref:rgant.adoc#_rgant-CollectionLayout_render[`@CollectionLayout(render=...)`] annotation to indicate if the collection should be visible or hidden by default
-* optional: use the xref:rgant.adoc#_rgant-CollectionLayout_sortedBy[`@CollectionLayout(sortedBy=...)`] annotation to specify a different comparator than the natural ordering
+** Use the xref:../../guides/rgant/rgant.adoc#_rgant-CollectionLayout_render[`@CollectionLayout(render=...)`] annotation to indicate if the collection should be visible or hidden by default
+* optional: use the xref:../../guides/rgant/rgant.adoc#_rgant-CollectionLayout_sortedBy[`@CollectionLayout(sortedBy=...)`] annotation to specify a different comparator than the natural ordering
 
 
 
@@ -368,10 +368,10 @@ Returning back to references, Isis also supports vector (multi-valued) reference
 The Wicket UI doesn't allow collections to be modified (added to/removed from). However, we can easily write actions to accomplish the same. Moreover, these actions can provide some additional business logic. For example: it probably shouldn't be possible to add an object twice into a collection, so it should not be presented in the list of choices/autoComplete; conversely, only those objects in the collection should be offered as choices to be removed.
 
 * Add domain actions to add/remove from the collection
-* to create objects, xref:ugfun.adoc#_ugfun_how-tos_class-structure_inject-services[inject] associated domain service
-** generally we recommend using the xref:rgant.adoc#_rgant-Inject[`@Inject`] annotation with either private or default visibility
-* the service itself should use xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`]
-* use the xref:rgant.adoc#_rgant-MemberOrder[`@MemberOrder(name=...)`] annotation to associate an action with a property or with a collection
+* to create objects, xref:../../guides/ugfun/ugfun.adoc#_ugfun_how-tos_class-structure_inject-services[inject] associated domain service
+** generally we recommend using the xref:../../guides/rgant/rgant.adoc#_rgant-Inject[`@Inject`] annotation with either private or default visibility
+* the service itself should use xref:../../guides/rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`]
+* use the xref:../../guides/rgant/rgant.adoc#_rgant-MemberOrder[`@MemberOrder(name=...)`] annotation to associate an action with a property or with a collection
 
 
 
@@ -380,11 +380,11 @@ The Wicket UI doesn't allow collections to be modified (added to/removed from).
 
 CSS classes can be associated with any class member (property, collection, action). But for actions in particular:
 
-* the bootstrap "btn" CSS classes can be used using the xref:rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout(cssClass=...)`] annotation
+* the bootstrap "btn" CSS classes can be used using the xref:../../guides/rgant/rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout(cssClass=...)`] annotation
 
-*  the http://fortawesome.github.io/Font-Awesome/icons/[Font Awesome] icons can be used using the xref:rgant.adoc#_rgant-ActionLayout_cssClassFa[`@ActionLayout(cssClassFa=...)`]
+*  the http://fortawesome.github.io/Font-Awesome/icons/[Font Awesome] icons can be used using the xref:../../guides/rgant/rgant.adoc#_rgant-ActionLayout_cssClassFa[`@ActionLayout(cssClassFa=...)`]
 
-It's also possible to use Font Awesome icons for the xref:ugfun.adoc#_ugfun_how-tos_ui-hints_object-titles-and-icons[domain object icon].
+It's also possible to use Font Awesome icons for the xref:../../guides/ugfun/ugfun.adoc#_ugfun_how-tos_ui-hints_object-titles-and-icons[domain object icon].
 
 So:
 - for some of the actions of your domain services or entities, annotate using `@ActionLayout(cssClass=...)` or `@ActionLayout(cssClassFa=...)`
@@ -397,7 +397,7 @@ So:
 Up to this point we've been using annotations (`@MemberOrder`, `@MemberGroupLayout`, `@Named`, `@PropertyLayout`, `@ParameterLayout`, `@ActionLayout` and so on) for UI hints. However, the feedback loop is not good: it requires us stopping the app, editing the code, recompiling and running again.
 So instead, all these UI hints (and more) can be specified dynamically, using a corresponding `.layout.xml` file. If edited while the app is running, it will be reloaded automatically (in IntelliJ, use Run&gt;Reload Changed Classes):
 
-* Delete the various hint annotations and instead specify layout hints using a xref:ugvw.adoc#_ugvw_layout_file-based[.layout.xml] file.
+* Delete the various hint annotations and instead specify layout hints using a  xref:../../guides/ugvw/ugvw.adoc#_ugvw_layout_file-based[.layout.xml] file.
 
 
 
@@ -415,27 +415,27 @@ Or, more pithily: "see it, use it, do it"
 
 === See it!
 
-* Use the xref:rgant.adoc#_rgant-Property_hidden[`Property(hidden=...)`] annotation to make properties invisible
-** likewise xref:rgant.adoc#_rgant-Collection_hidden[`@Collection(hidden=...)`] for collections
-** the xref:rgant.adoc#_rgant-Programmatic[`@Programmatic`]  annotation can also be used and in many cases is to be preferred; the difference is that the latter means the member is not part of the Apache Isis metamodel.
-* Use the xref:rgcms.adoc#_rgcms_methods_prefixes_hide[`hide...()`] supporting method on properties, collections and actions to make a property/collection/action invisible according to some imperative rule
+* Use the xref:../../guides/rgant/rgant.adoc#_rgant-Property_hidden[`Property(hidden=...)`] annotation to make properties invisible
+** likewise xref:../../guides/rgant/rgant.adoc#_rgant-Collection_hidden[`@Collection(hidden=...)`] for collections
+** the xref:../../guides/rgant/rgant.adoc#_rgant-Programmatic[`@Programmatic`]  annotation can also be used and in many cases is to be preferred; the difference is that the latter means the member is not part of the Apache Isis metamodel.
+* Use the xref:../../guides/rgcms/rgcms.adoc#_rgcms_methods_prefixes_hide[`hide...()`] supporting method on properties, collections and actions to make a property/collection/action invisible according to some imperative rule
 
 
 === Use it!
 
-* Use the xref:rgant.adoc#_rgant-Property_editing[`Property(editing=...)`] annotation to make property read-only
-** likewise xref:rgant.adoc#_rgant-Collection_editing[`@Collection(editing=...)`] for collections
-** alternatively, use xref:rgant.adoc#_rgant-DomainObject_editing[`@DomainObject(editing=...)`] to disable editing for all properties/collections
-* Use the xref:rgcms.adoc#_rgcms_methods_prefixes_disable[`disable...()`] supporting method on properties and actions to make a property/action disabled according to some imperative rule
+* Use the xref:../../guides/rgant/rgant.adoc#_rgant-Property_editing[`Property(editing=...)`] annotation to make property read-only
+** likewise xref:../../guides/rgant/rgant.adoc#_rgant-Collection_editing[`@Collection(editing=...)`] for collections
+** alternatively, use xref:../../guides/rgant/rgant.adoc#_rgant-DomainObject_editing[`@DomainObject(editing=...)`] to disable editing for all properties/collections
+* Use the xref:../../guides/rgcms/rgcms.adoc#_rgcms_methods_prefixes_disable[`disable...()`] supporting method on properties and actions to make a property/action disabled according to some imperative rule
 
 
 === Do it!
 
-* use the xref:rgant.adoc#_rgant-Property_regexPattern[`@Property(regexPattern=...)`] annotation to specify a regex pattern for properties, and use xref:rgant.adoc#_rgant-Parameter_regexPattern[`@Parameter(regexPattern=...)`] for parameters
-* use the xref:rgant.adoc#_rgant-Property_maxLength[`@Property(maxLength=...)`] annotation to indicate a maxmum number of characters, and xref:rgant.adoc#_rgant-Parameter_maxLength[`@Parameter(maxLength=...)`] for parameters
-* Use the xref:rgcms.adoc#_rgcms_methods_prefixes_validate[`validate...()`] supporting method on properties or action parameter
+* use the xref:../../guides/rgant/rgant.adoc#_rgant-Property_regexPattern[`@Property(regexPattern=...)`] annotation to specify a regex pattern for properties, and use xref:../../guides/rgant/rgant.adoc#_rgant-Parameter_regexPattern[`@Parameter(regexPattern=...)`] for parameters
+* use the xref:../../guides/rgant/rgant.adoc#_rgant-Property_maxLength[`@Property(maxLength=...)`] annotation to indicate a maxmum number of characters, and xref:../../guides/rgant/rgant.adoc#_rgant-Parameter_maxLength[`@Parameter(maxLength=...)`] for parameters
+* Use the xref:../../guides/rgcms/rgcms.adoc#_rgcms_methods_prefixes_validate[`validate...()`] supporting method on properties or action parameter
 * optional: for any data type:
-** use the xref:rgant.adoc#_rgant-Property_mustSatisfy[`Property(mustSatisfy=...)`] and xref:rgant.adoc#_rgant-Parameter_mustSatisfy[`Parameter(mustSatisfy=...)`] annotations to specify arbitrary constraints on properties and parameters
+** use the xref:../../guides/rgant/rgant.adoc#_rgant-Property_mustSatisfy[`Property(mustSatisfy=...)`] and xref:../../guides/rgant/rgant.adoc#_rgant-Parameter_mustSatisfy[`Parameter(mustSatisfy=...)`] annotations to specify arbitrary constraints on properties and parameters
 
 
 
@@ -444,7 +444,7 @@ Or, more pithily: "see it, use it, do it"
 
 The Wicket UI will automatically invoke the "home page" action, if available. This is a no-arg action of one of the domain services, that can return either an object (eg representing the current user) or a standalone action.
 
-* Add the xref:rgant.adoc#_rgant-HomePage[`@HomePage`] annotation to one (no more) of the domain services' no-arg actions
+* Add the xref:../../guides/rgant/rgant.adoc#_rgant-HomePage[`@HomePage`] annotation to one (no more) of the domain services' no-arg actions
 
 
 
@@ -454,7 +454,7 @@ The Wicket UI will automatically invoke the "home page" action, if available. Th
 To ensure testability, there should be no dependencies on system time, for example usage of `LocalDate.now()`. Instead the domain objects should delegate to the provided `ClockService`.
 
 * remove any dependencies on system time (eg defaults for date/time action parameters)
-* inject xref:rgsvc.adoc#_rgsvc_api_ClockService[`ClockService`]
+* inject xref:../../guides/rgsvc/rgsvc.adoc#_rgsvc_api_ClockService[`ClockService`]
 * call `ClockService.now()` etc where required.
 
 
@@ -474,7 +474,7 @@ Finally, note that the layout of contributed actions/collections/properties can
 
 * Write a new domain service
 ** by convention, called "XxxContributions"
-** annotate with xref:rgant.adoc#_rgant-DomainService_nature[`@DomainService(nature=NatureOfService.VIEW_CONTRIBUTIONS_ONLY)`]
+** annotate with xref:../../guides/rgant/rgant.adoc#_rgant-DomainService_nature[`@DomainService(nature=NatureOfService.VIEW_CONTRIBUTIONS_ONLY)`]
 *** indicates that all of the service's actions should _not_ be included in the main application menu bar
 *** should be rendered "as if" an action of the entity
 * Write an action accepting &gt;1 args:
@@ -487,7 +487,7 @@ Finally, note that the layout of contributed actions/collections/properties can
 * Write a query-only action accepting exactly 1 arg (a domain entity)
 * returning a collection, list or set
 * For this action:
-** add the xref:rgant.adoc#_rgant-ActionLayout_contributedAs[`@ActionLayout(contributedAs=ASSOCIATION)`] annotation
+** add the xref:../../guides/rgant/rgant.adoc#_rgant-ActionLayout_contributedAs[`@ActionLayout(contributedAs=ASSOCIATION)`] annotation
 ** should be rendered in the UI "as if" a collection of the entity
 * use `.layout.json` to position as required
 
@@ -497,7 +497,7 @@ Finally, note that the layout of contributed actions/collections/properties can
 * As for contributed collections, write a new domain service with a query-only action accepting exactly 1 arg (a domain entity); except:
 ** returning a scalar value rather than a collection
 * For this action:
-** add the xref:rgant.adoc#_rgant-ActionLayout_contributedAs[`@ActionLayout(contributedAs=ASSOCIATION)`] annotation
+** add the xref:../../guides/rgant/rgant.adoc#_rgant-ActionLayout_contributedAs[`@ActionLayout(contributedAs=ASSOCIATION)`] annotation
 * should be rendered in the UI "as if" a property of the entity
 * use `.layout.json` to position as required
 
@@ -509,10 +509,10 @@ Another way in which Apache Isis helps you keep your application nicely modulari
 
 Under the covers Apache Isis uses the https://code.google.com/p/guava-libraries/wiki/EventBusExplained[Guava event bus] and subscribers (always domain services) subscribe by writing methods annotated with `@com.google.common.eventbus.Subscribe` annotation.
 
-By default the events generated are `ActionDomainEvent.Default` (for actions) and `PropertyDomainEvent.Default` (for properties). Subclasses of these can be specified using the xref:rgant.adoc#_rgant-Action_domainEvent[`@Action(domainEvent=...)`] or xref:rgant.adoc#_rgant-Property_domainEvent[`Property(domainEvent=...)`] for properties.
+By default the events generated are `ActionDomainEvent.Default` (for actions) and `PropertyDomainEvent.Default` (for properties). Subclasses of these can be specified using the xref:../../guides/rgant/rgant.adoc#_rgant-Action_domainEvent[`@Action(domainEvent=...)`] or xref:../../guides/rgant/rgant.adoc#_rgant-Property_domainEvent[`Property(domainEvent=...)`] for properties.
 
 
-Using the guidance in the docs for the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`]:
+Using the guidance in the docs for the xref:../../guides/rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`]:
 
 * write a domain service subscriber to subscribe to events
 * use the domain service to perform log events
@@ -522,7 +522,7 @@ Using the guidance in the docs for the xref:rgsvc.adoc#_rgsvc_api_EventBusServic
 
 == Bulk actions
 
-Bulk actions are actions that can be invoked on a collection of actions, that is on collections returned by invoking an action. Actions are specified as being bulk actions using the xref:rgant.adoc#_rgant-Action_invokeOn[`@action(invokeOn=OBJECT_AND_COLLECTION)`] annotation.
+Bulk actions are actions that can be invoked on a collection of actions, that is on collections returned by invoking an action. Actions are specified as being bulk actions using the xref:../../guides/rgant/rgant.adoc#_rgant-Action_invokeOn[`@action(invokeOn=OBJECT_AND_COLLECTION)`] annotation.
 
 [NOTE]
 ====
@@ -531,12 +531,12 @@ Note that currently (1.8.0) only no-arg actions can be specified as bulk actions
 
 Thus:
 * Write a no-arg action for your domain entity, annotate with `@Action(invokeOn=...)`
-* Inject the xref:rgsvc.adoc#_rgsvc_api_ActionInvocationContext[`ActionInteractionContext`] (request-scoped) service
+* Inject the xref:../../guides/rgsvc/rgsvc.adoc#_rgsvc_api_ActionInvocationContext[`ActionInteractionContext`] (request-scoped) service
 * Use the `ActionInteractionContext` service to determine whether the action was invoked in bulk or as a regular action.
 * return null if invoked on a collection; the Wicket viewer will go back to the original collection
 ** (if return non-null, then Wicket viewer will navigate to the object of the last invocation generally not what is required)
 
-The similar xref:rgsvc.adoc#_rgsvc_api_Scratchpad[`Scratchpad`] (request-scoped) domain service is a good way to share information between bulk action invocations:
+The similar xref:../../guides/rgsvc/rgsvc.adoc#_rgsvc_api_Scratchpad[`Scratchpad`] (request-scoped) domain service is a good way to share information between bulk action invocations:
 
 * Inject the `Scratchpad` domain service
 * for each action, store state (eg a running total)
@@ -547,7 +547,7 @@ The similar xref:rgsvc.adoc#_rgsvc_api_Scratchpad[`Scratchpad`] (request-scoped)
 
 == Performance tuning
 
-The xref:rgsvc.adoc#_rgsvc_api_QueryResultsCache[`QueryResultsCache`] (request-scoped) domain service allows arbitrary objects to be cached for the duration of a request.
+The xref:../../guides/rgsvc/rgsvc.adoc#_rgsvc_api_QueryResultsCache[`QueryResultsCache`] (request-scoped) domain service allows arbitrary objects to be cached for the duration of a request.
 
 This can be helpful for "naive" code which would normally make the same query within a loop.
 
@@ -559,7 +559,7 @@ This can be helpful for "naive" code which would normally make the same query wi
 
 == Extending the Wicket UI
 
-Each element in the Wicket viewer (entity form, properties, collections, action button etc) is a component, each created by a internal API (`ComponentFactory`, described xref:ugvw.adoc#_ugvw_extending[here]). For collections there can be multiple views, and the Wicket viewer provides a view selector drop down (top right of each collection panel).
+Each element in the Wicket viewer (entity form, properties, collections, action button etc) is a component, each created by a internal API (`ComponentFactory`, described xref:../../guides/ugvw/ugvw.adoc#_ugvw_extending[here]). For collections there can be multiple views, and the Wicket viewer provides a view selector drop down (top right of each collection panel).
 
 Moreover, we can add additional views. In this section we'll explore some of these, already provided through http://www.isisaddons.org/[Isis addons] (not ASF).
 
@@ -607,7 +607,7 @@ In most cases users can accomplish the business operations they need by invoking
 
 Also, if using Apache Isis' REST API then the REST client may be a native application (on a smartphone or tablet, say) that is deployed by a third party. In these cases exposing the entities directly would be inadvisable because a refactoring of the domain entity would change the REST API and probably break that REST client.
 
-To support these use cases, Apache Isis therefore allows you to write a view model, either by annotating the class with xref:rgant.adoc#_rgant-ViewModel[`@ViewModel`] or (for more control) by implementing the xref:rgcms.adoc#_rgcms_classes_super_AbstractViewModel[`ViewModel`] interface.
+To support these use cases, Apache Isis therefore allows you to write a view model, either by annotating the class with xref:../../guides/rgant/rgant.adoc#_rgant-ViewModel[`@ViewModel`] or (for more control) by implementing the xref:../../guides/rgcms/rgcms.adoc#_rgcms_classes_super_AbstractViewModel[`ViewModel`] interface.
 
 * build a view model summarizing the state of the app (a "dashboard")
 * write a new `@HomePage` domain service action returning this dashboard viewmodel (and remove the `@HomePage` annotation from any other domain service if present)
@@ -624,7 +624,7 @@ Up to this point we've been introducing the features of Isis and building out ou
 
 Unit testing domain entities and domain services is easy; just use JUnit and mocking libraries to mock out interactions with domain services.
 
-https://code.google.com/p/mockito/[Mockito] seems to be the current favourite among Java developers for mocking libraries, but if you use JMock then you'll find we provide a `JUnitRuleMockery2` class and a number of other utility classes, documented xref:ugtst.adoc#_ugtst_unit-test-support[here].
+https://code.google.com/p/mockito/[Mockito] seems to be the current favourite among Java developers for mocking libraries, but if you use JMock then you'll find we provide a `JUnitRuleMockery2` class and a number of other utility classes, documented xref:../../guides/ugtst/ugtst.adoc#_ugtst_unit-test-support[here].
 
 * write some unit tests (adapt from the unit tests in the `myapp-dom` Maven module).
 
@@ -662,7 +662,7 @@ change back to:
 
 There will probably be some compile issues to fix up once you've done this; comment out all code that doesn't compile.
 
-Isis has great support for writing xref:ugtst.adoc#_ugtst_integ-test-support[integration tests]; well-written integration tests should leverage fixture scripts and use the xref:rgsvc.adoc#_rgsvc_api_WrapperFactory[`@WrapperFactory`] domain service.
+Isis has great support for writing xref:../../guides/ugtst/ugtst.adoc#_ugtst_integ-test-support[integration tests]; well-written integration tests should leverage fixture scripts and use the xref:../../guides/rgsvc/rgsvc.adoc#_rgsvc_api_WrapperFactory[`@WrapperFactory`] domain service.
 
 * use the tests from the original archetype and the documentation on the website to develop integration tests for your app's functionality.
 
@@ -673,7 +673,7 @@ Isis has great support for writing xref:ugtst.adoc#_ugtst_integ-test-support[int
 
 The REST API generated by Apache Isis conforms to the Restful Objects specification. Apache Isis 1.8.0 provides experimental support to allow the representations to be customized.
 
-* as per xref:ugvro.adoc#__ugvro_simplified-representations_configuration-properties[the documentation], configure the Restful Objects viewer to generate a simplified object representation: +
+* as per xref:../../guides/ugvro/ugvro.adoc#__ugvro_simplified-representations_configuration-properties[the documentation], configure the Restful Objects viewer to generate a simplified object representation: +
 +
 [source,ini]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/4807f4c2/adocs/documentation/src/main/asciidoc/release-notes/_release-notes_1.9.0.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/release-notes/_release-notes_1.9.0.adoc b/adocs/documentation/src/main/asciidoc/release-notes/_release-notes_1.9.0.adoc
index ba249ee..6663242 100644
--- a/adocs/documentation/src/main/asciidoc/release-notes/_release-notes_1.9.0.adoc
+++ b/adocs/documentation/src/main/asciidoc/release-notes/_release-notes_1.9.0.adoc
@@ -7,7 +7,7 @@
 
 
 
-Apache Isis 1.9.0 provides various new "under-the-cover" features, such as `AppManifest` for simplified bootstrapping, and content negotiation support within xref:ugvro.adoc#[RestfulObjects viewer].  It also updates the DataNucleus version to DN 4.1.x.
+Apache Isis 1.9.0 provides various new "under-the-cover" features, such as `AppManifest` for simplified bootstrapping, and content negotiation support within xref:../guides/ugvro/ugvro.adoc#[RestfulObjects viewer].  It also updates the DataNucleus version to DN 4.1.x.
 
 This release was also the first to include the updated Asciidoc website.
 

[11/58] [abbrv] isis git commit: ISIS-1521: fixes xref links between guides

[da...@apache.org]

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModel.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModel.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModel.adoc
index 000586c..65becc2 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModel.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModel.adoc
@@ -33,9 +33,9 @@ Note that there is a `DomainObjectContainer#newViewModelInstance(.)`; this is fo
 ====
 
 
-The view model's memento will be derived from the value of the view model object's properties. Any xref:rgant.adoc#_rgant-Property_notPersisted[`@Property#notPersisted()`] properties will be excluded from the memento, as will any xref:rgant.adoc#_rgant-Programmatic[`@Programmatic`] properties. Properties that are merely xref:rgant.adoc#_rgant-Property_hidden[hidden] _are_ included in the memento.
+The view model's memento will be derived from the value of the view model object's properties. Any xref:../rgant/rgant.adoc#_rgant-Property_notPersisted[`@Property#notPersisted()`] properties will be excluded from the memento, as will any xref:../rgant/rgant.adoc#_rgant-Programmatic[`@Programmatic`] properties. Properties that are merely xref:../rgant/rgant.adoc#_rgant-Property_hidden[hidden] _are_ included in the memento.
 
-Only properties supported by the configured xref:rgsvc.adoc#_rgsvc_api_MementoService[`MementoService`] can be used. The default implementation supports all the value types and persisted entities.
+Only properties supported by the configured xref:../rgsvc/rgsvc.adoc#_rgsvc_api_MementoService[`MementoService`] can be used. The default implementation supports all the value types and persisted entities.
 
 (As of 1.8.0) there are some limitations:
 * view models cannot hold collections other view models (simple properties _are_ supported, though)
@@ -44,7 +44,7 @@ Only properties supported by the configured xref:rgsvc.adoc#_rgsvc_api_MementoSe
 
 [WARNING]
 ====
-The `@ViewModel` does not allow the objectType to be specified, meaning that it is incompatible with the metamodel validation check ennabled by the xref:rgcfg.adoc#__rgcfg_configuring-core_metamodel-validation[`explicitObjectType`] configuration property.
+The `@ViewModel` does not allow the objectType to be specified, meaning that it is incompatible with the metamodel validation check ennabled by the xref:../rgcfg/rgcfg.adoc#__rgcfg_configuring-core_metamodel-validation[`explicitObjectType`] configuration property.
 
-Instead, use xref:rgant.adoc#_rgant_DomainObject_nature[`@DomainObject#nature()`] with `Nature.VIEW_MODEL`, and specify xref:rgant.adoc#_rgant_DomainObject_objectType[`@DomainObject#objectType()`].
+Instead, use xref:../rgant/rgant.adoc#_rgant_DomainObject_nature[`@DomainObject#nature()`] with `Nature.VIEW_MODEL`, and specify xref:../rgant/rgant.adoc#_rgant_DomainObject_objectType[`@DomainObject#objectType()`].
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout.adoc
index 8328c21..21f16ac 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout.adoc
@@ -5,8 +5,8 @@
 :_imagesdir: images/
 
 
-The `@ViewModelLayout` annotation is identical to the xref:rgant.adoc#_rgant-DomainObjectLayout[`@DomainObjectLayout`], but is provided
-for symmetry with domain objects that have been annotated using xref:rgant.adoc#_rgant-ViewModel[`@ViewModel`] (rather than xref:rgant.adoc#_rgant-DomainObject_nature[`@DomainObject(nature=VIEW_MODEL)`]).
+The `@ViewModelLayout` annotation is identical to the xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout[`@DomainObjectLayout`], but is provided
+for symmetry with domain objects that have been annotated using xref:../rgant/rgant.adoc#_rgant-ViewModel[`@ViewModel`] (rather than xref:../rgant/rgant.adoc#_rgant-DomainObject_nature[`@DomainObject(nature=VIEW_MODEL)`]).
 
 
 The table below summarizes the annotation's attributes.
@@ -20,12 +20,12 @@ The table below summarizes the annotation's attributes.
 | Description
 
 
-|xref:rgant.adoc#_rgant-ViewModelLayout_cssclass[`cssClass()`]
+|xref:../rgant/rgant.adoc#_rgant-ViewModelLayout_cssclass[`cssClass()`]
 |Any string valid as a CSS class
-|the css class that a domain class (type) should have, to allow more targetted styling in xref:rgcfg.adoc#_rgcfg_application-specific_application-css[`application.css`]
+|the css class that a domain class (type) should have, to allow more targetted styling in xref:../rgcfg/rgcfg.adoc#_rgcfg_application-specific_application-css[`application.css`]
 
 
-|xref:rgant.adoc#_rgant-ViewModelLayout_cssClassFa[`cssClassFa()`]
+|xref:../rgant/rgant.adoc#_rgant-ViewModelLayout_cssClassFa[`cssClassFa()`]
 |Any valid link:http://fortawesome.github.io/Font-Awesome/[Font awesome] icon name
 |specify a font awesome icon for the action's menu link or icon. +
 
@@ -36,25 +36,25 @@ The table below summarizes the annotation's attributes.
 |Currently unused.
 
 
-|xref:rgant.adoc#_rgant-ViewModelLayout_describedAs[`describedAs()`]
+|xref:../rgant/rgant.adoc#_rgant-ViewModelLayout_describedAs[`describedAs()`]
 |String.
 |description of this class, eg to be rendered in a tooltip.
 
 
 
-|xref:rgant.adoc#_rgant-ViewModelLayout_named[`named()`]
+|xref:../rgant/rgant.adoc#_rgant-ViewModelLayout_named[`named()`]
 |String.
 |to override the name inferred from the action's name in code. +
 
 A typical use case is if the desired name is a reserved Java keyword, such as `default` or `package`.
 
 
-|xref:rgant.adoc#_rgant-ViewModelLayout_paged[`paged()`]
+|xref:../rgant/rgant.adoc#_rgant-ViewModelLayout_paged[`paged()`]
 |Positive integer
 |the page size for instances of this class when rendered within a table (as returned from an action invocation)
 
 
-|xref:rgant.adoc#_rgant-ViewModelLayout_plural[`plural()`]
+|xref:../rgant/rgant.adoc#_rgant-ViewModelLayout_plural[`plural()`]
 |String.
 |the plural name of the class
 
@@ -77,7 +77,7 @@ For example:
 )
 public class CategoryPieChart { ... }
 ----
-<1> this annotation is intended for use with `@ViewModel`.  If a view model has been specified using the equivalent xref:rgant.adoc#_rgant-DomainObject_nature[`@DomainObject(nature=Nature.VIEW_MODEL)`], then we recommend you use xref:rgant.adoc#_rgant-DomainObjectLayout[`@DomainObjectLayout`] instead.
+<1> this annotation is intended for use with `@ViewModel`.  If a view model has been specified using the equivalent xref:../rgant/rgant.adoc#_rgant-DomainObject_nature[`@DomainObject(nature=Nature.VIEW_MODEL)`], then we recommend you use xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout[`@DomainObjectLayout`] instead.
 
 
 [NOTE]

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout_cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout_cssClass.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout_cssClass.adoc
index 0bd9bee..167d28e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout_cssClass.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout_cssClass.adoc
@@ -6,9 +6,9 @@
 
 
 
-The `cssClass()` attribute can be used to render additional CSS classes in the HTML (a wrapping `<div>`) that represents the view model.   xref:rgcfg.adoc#_rgcfg_application-specific_application-css[Application-specific CSS] can then be used to target and adjust the UI representation of that particular element.
+The `cssClass()` attribute can be used to render additional CSS classes in the HTML (a wrapping `<div>`) that represents the view model.   xref:../rgcfg/rgcfg.adoc#_rgcfg_application-specific_application-css[Application-specific CSS] can then be used to target and adjust the UI representation of that particular element.
 
-This attribute can also be applied to xref:rgant.adoc#_rgant-DomainObjectLayout_cssClass[domain objects], xref:rgant.adoc#_rgant-ActionLayout_cssClass[actions] xref:rgant.adoc#_rgant-PropertyLayout_cssClass[properties],  xref:rgant.adoc#_rgant-CollectionLayout_cssClass[collections] and xref:rgant.adoc#_rgant-ParameterLayout_cssClass[parameters].
+This attribute can also be applied to xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_cssClass[domain objects], xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClass[actions] xref:../rgant/rgant.adoc#_rgant-PropertyLayout_cssClass[properties],  xref:../rgant/rgant.adoc#_rgant-CollectionLayout_cssClass[collections] and xref:../rgant/rgant.adoc#_rgant-ParameterLayout_cssClass[parameters].
 
 
 For example:
@@ -25,6 +25,6 @@ public class CategoryPieChart { ... }
 
 [NOTE]
 ====
-The similar xref:rgant.adoc#_rgant-ViewModelLayout_cssClassFa[`@ViewModelLayout#cssClassFa()`] annotation attribute is also used as a hint to apply CSS, but in particular to allow http://fortawesome.github.io/Font-Awesome/icons/[Font Awesome icons] to be rendered as the icon for classes.
+The similar xref:../rgant/rgant.adoc#_rgant-ViewModelLayout_cssClassFa[`@ViewModelLayout#cssClassFa()`] annotation attribute is also used as a hint to apply CSS, but in particular to allow http://fortawesome.github.io/Font-Awesome/icons/[Font Awesome icons] to be rendered as the icon for classes.
 ====
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout_cssClassFa.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout_cssClassFa.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout_cssClassFa.adoc
index b93ffd7..e42d659 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout_cssClassFa.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout_cssClassFa.adoc
@@ -9,10 +9,10 @@
 
 The `cssClassFa()` attribute is used to specify the name of a link:http://fortawesome.github.io/Font-Awesome/icons/[Font Awesome icon] name, to be rendered as the domain object's icon.
 
-These attribute can also be applied to xref:rgant.adoc#_rgant-DomainObjectLayout_cssClassFa[domain objects] to specify the object's icon, and to xref:rgant.adoc#_rgant-ActionLayout_cssClassFa[actions] to specify an icon for the action's representation as a button or menu item.
+These attribute can also be applied to xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_cssClassFa[domain objects] to specify the object's icon, and to xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClassFa[actions] to specify an icon for the action's representation as a button or menu item.
 
 
-If necessary the icon specified can be overridden by a particular object instance using the xref:rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`] method.
+If necessary the icon specified can be overridden by a particular object instance using the xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`] method.
 
 
 
@@ -36,6 +36,6 @@ The related `cssClassFaPosition()` attribute is currently unused for domain obje
 
 [NOTE]
 ====
-The similar xref:rgant.adoc#_rgant-ViewModelLayout_cssClass[`@ViewModelLayout#cssClass()`] annotation attribute is also used as a hint to apply CSS, but for wrapping the representation of an object or object member so that it can be styled in an application-specific way.
+The similar xref:../rgant/rgant.adoc#_rgant-ViewModelLayout_cssClass[`@ViewModelLayout#cssClass()`] annotation attribute is also used as a hint to apply CSS, but for wrapping the representation of an object or object member so that it can be styled in an application-specific way.
 ====
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout_describedAs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout_describedAs.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout_describedAs.adoc
index 355f00a..1646f4e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout_describedAs.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout_describedAs.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-The `describedAs()` attribute is used to provide a short description of the view model to the user.  In the xref:ugvw.adoc#[Wicket viewer] it is displayed as a 'tool tip'.  The `describedAs()` attribute can also be specified for xref:rgant.adoc#_rgant-CollectionLayout_describedAs[collections],  xref:rgant.adoc#_rgant-PropertyLayout_describedAs[properties], xref:rgant.adoc#_rgant-ActionLayout_describedAs[actions], xref:rgant.adoc#_rgant-ParameterLayout_describedAs[parameters] and xref:rgant.adoc#_rgant-DomainObjectLayout_describedAs[domain objects].
+The `describedAs()` attribute is used to provide a short description of the view model to the user.  In the xref:ugvw.adoc#[Wicket viewer] it is displayed as a 'tool tip'.  The `describedAs()` attribute can also be specified for xref:../rgant/rgant.adoc#_rgant-CollectionLayout_describedAs[collections],  xref:../rgant/rgant.adoc#_rgant-PropertyLayout_describedAs[properties], xref:../rgant/rgant.adoc#_rgant-ActionLayout_describedAs[actions], xref:../rgant/rgant.adoc#_rgant-ParameterLayout_describedAs[parameters] and xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_describedAs[domain objects].
 
 For example:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout_named.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout_named.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout_named.adoc
index 08bc797..2998e40 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout_named.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout_named.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-The `named()` attribute explicitly specifies the view model's name, overriding the name that would normally be inferred from the Java source code.  This attribute can also be specified for xref:rgant.adoc#_rgant-ActionLayout_named[actions], xref:rgant.adoc#_rgant-CollectionLayout_named[collections], xref:rgant.adoc#_rgant-PropertyLayout_named[properties], xref:rgant.adoc#_rgant-ParameterLayout_named[parameters], xref:rgant.adoc#_rgant-DomainObjectLayout_named[domain objects] and xref:rgant.adoc#_rgant-DomainServiceLayout_named[domain services].
+The `named()` attribute explicitly specifies the view model's name, overriding the name that would normally be inferred from the Java source code.  This attribute can also be specified for xref:../rgant/rgant.adoc#_rgant-ActionLayout_named[actions], xref:../rgant/rgant.adoc#_rgant-CollectionLayout_named[collections], xref:../rgant/rgant.adoc#_rgant-PropertyLayout_named[properties], xref:../rgant/rgant.adoc#_rgant-ParameterLayout_named[parameters], xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_named[domain objects] and xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_named[domain services].
 
 [TIP]
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout_paged.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout_paged.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout_paged.adoc
index f06356d..6ba7e74 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout_paged.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout_paged.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-The `paged()` attribute specifies the number of rows to display in a standalone collection, as returned from an action invocation.  This attribute can also be applied to xref:rgant.adoc#_rgant-CollectionLayout_paged[collections] and xref:rgant.adoc#_rgant-DomainObjectLayout_paged[domain objects].
+The `paged()` attribute specifies the number of rows to display in a standalone collection, as returned from an action invocation.  This attribute can also be applied to xref:../rgant/rgant.adoc#_rgant-CollectionLayout_paged[collections] and xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_paged[domain objects].
 
 
 
@@ -29,6 +29,6 @@ public class OrderAnalysis {
 ----
 
 
-It is also possible to specify a global default for the page size of standalone collections, using the xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.viewer.paged.standalone`.
+It is also possible to specify a global default for the page size of standalone collections, using the xref:../rgcfg/rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.viewer.paged.standalone`.
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout_plural.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout_plural.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout_plural.adoc
index 4cc2180..e178f51 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout_plural.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout_plural.adoc
@@ -10,7 +10,7 @@ When Apache Isis displays a standalone collection of several objects, it will la
 
 By default the plural name will be derived from the end of the singular name, with support for some basic English language defaults (eg using "ies" for names ending with a "y").
 
-The `plural()` attribute allows the plural form of the class name to be specified explicitly.  This attribute is also supported for xref:rgant.adoc#_rgant-DomainObjectLayout_plural[domain objects].
+The `plural()` attribute allows the plural form of the class name to be specified explicitly.  This attribute is also supported for xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_plural[domain objects].
 
 For example:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModel_objectType.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModel_objectType.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModel_objectType.adoc
index bdd4008..1ed0889 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModel_objectType.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModel_objectType.adoc
@@ -11,12 +11,12 @@ This value is used internally to generate a string representation of an objects
 This can appear in several contexts, including:
 
 * as the value of `Bookmark#getObjectType()` and in the `toString()` value of `Bookmark`
- (see xref:rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`])
+ (see xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`])
  ** and thus in the "table-of-two-halves" pattern, as per (non-ASF) http://github.com/isisaddons/isis-module-poly[Isis addons' poly] module
-* in the serialization of `OidDto` in the xref:rgcms.adoc#_rgcms_schema-cmd[command] and xref:rgcms.adoc#_rgcms_schema-ixn[interaction] schemas
+* in the serialization of `OidDto` in the xref:../rgcms/rgcms.adoc#_rgcms_schema-cmd[command] and xref:../rgcms/rgcms.adoc#_rgcms_schema-ixn[interaction] schemas
 * in the URLs of the xref:ugvro.adoc#[RestfulObjects viewer]
 * in the URLs of the xref:ugvw.adoc#[Wicket viewer] (in general and in particular if xref:ugvw.adoc#_ugvw_features_hints-and-copy-url[copying URLs])
-* in XML snapshots generated by the xref:rgsvc.adoc#_rgsvc_api_XmlSnapshotService[`XmlSnapshotService`]
+* in XML snapshots generated by the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_XmlSnapshotService[`XmlSnapshotService`]
 
 
 
@@ -39,9 +39,9 @@ public class Order {
 
 The rules of precedence are:
 
-1. xref:rgant.adoc#_rgant_Discriminator[`@Discriminator`]
-2. `@DomainObject#objectType`, or xref:rgant.adoc#_rgant_ViewModel_objectType[`@ViewModel#objectType()`], or xref:rgant.adoc#_rgant_aaa_deprecated[`@ObjectType`] (deprecated)
-3. xref:rgant.adoc#_rgant_PersistenceCapable[`@PersistenceCapable`], if at least the `schema` attribute is defined.  +
+1. xref:../rgant/rgant.adoc#_rgant_Discriminator[`@Discriminator`]
+2. `@DomainObject#objectType`, or xref:../rgant/rgant.adoc#_rgant_ViewModel_objectType[`@ViewModel#objectType()`], or xref:../rgant/rgant.adoc#_rgant_aaa_deprecated[`@ObjectType`] (deprecated)
+3. xref:../rgant/rgant.adoc#_rgant_PersistenceCapable[`@PersistenceCapable`], if at least the `schema` attribute is defined.  +
 +
 If both `schema` and `table` are defined, then the value is "`schema.table`".
 If only `schema` is defined, then the value is "`schema.className`".

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-XmlJavaTypeAdapter.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-XmlJavaTypeAdapter.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-XmlJavaTypeAdapter.adoc
index 02cb8ef..2b2a034 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-XmlJavaTypeAdapter.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-XmlJavaTypeAdapter.adoc
@@ -8,7 +8,7 @@
 The JAXB `@XmlJavaTypeAdapter` annotation is used with the framework-provided
 `PersistentEntityAdapter` to instruct JAXB to serialize references to persistent entities using the canonical
 `OidDto` complex type: the object's type and its identifier.  This is the formal XML equivalent to the `Bookmark`
-provided by the xref:rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`].
+provided by the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`].
 
 For example:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-XmlRootElement.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-XmlRootElement.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-XmlRootElement.adoc
index 815cac8..ac3b58d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-XmlRootElement.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-XmlRootElement.adoc
@@ -13,13 +13,13 @@ A view model is a non-persisted domain object whose state is converted to/from a
 JAXB-annotated object this memento is its XML representation.  JAXB generally requires that the root element of the
 XML representation is annotated with `@XmlRootElement`.  Apache Isis makes this a mandatory requirement.
 
-In comparison to using either the xref:rgcms.adoc#_rgcms_classes_super_ViewModel[`ViewModel`] interface or the
-xref:rgant.adoc#_rgant-ViewModel[`@ViewModel`] annotation, using `@XmlRootElement` has a couple of
+In comparison to using either the xref:../rgcms/rgcms.adoc#_rgcms_classes_super_ViewModel[`ViewModel`] interface or the
+xref:../rgant/rgant.adoc#_rgant-ViewModel[`@ViewModel`] annotation, using `@XmlRootElement` has a couple of
 significant advantages:
 
 * the view model can be used as a "canonical" DTO, for example when accessing data using the
 xref:ugvro.adoc#[RestfulObjects viewer] in combination with the
-xref:rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`]. +
+xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`]. +
 +
 This provides a stable and
 versioned API to access data in XML format using whatever client-side technology may be appropriate.
@@ -31,15 +31,15 @@ If using `ViewModel` interface then arbitrary state (including that of collectio
 all the code by hand
 
 The main disadvantages of using JAXB-annotated view models is that any referenced persistent entity must be annotated
-with the xref:rgant.adoc#_rgant-XmlJavaTypeAdapter[`@XmlJavaTypeAdapter`], using the
+with the xref:../rgant/rgant.adoc#_rgant-XmlJavaTypeAdapter[`@XmlJavaTypeAdapter`], using the
 framework-provided `PersistentEntityAdapter`.  This adapter converts any references to such domain entities using the
-`oidDto` complex type (as defined by the Apache Isis xref:rgcms.adoc#_rgcms_schema-common[common schema]):
+`oidDto` complex type (as defined by the Apache Isis xref:../rgcms/rgcms.adoc#_rgcms_schema-common[common schema]):
 the object's type and its identifier.
 
 [TIP]
 ====
 The memento string for view models is converted into a form compatible with use within a URL.  This is performed by the
-xref:rgsvc.adoc#_rgsvc_spi_UrlEncodingService[`UrlEncodingService`], the default implementation of which
+xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UrlEncodingService[`UrlEncodingService`], the default implementation of which
 simply encodes to base 64.  If the view model XML graph is too large to be serialized to a string, then an alternative
 implementation (eg which maps XML strings to a GUID, say) can be configured using the technique described in
 xref:rg.adoc#_ugfun_how-tos_replacing-default-service-implementations[here] in the user guide.
@@ -75,7 +75,7 @@ Although (like any other viewmodel) a JAXB-annotated can have behaviour (actions
 the DTO "clean", just focused on specifying the data contract.
 
 Behaviour can therefore be provided using xref:ugbtb.adoc#_ugbtb_decoupling_mixins[mixins] (annotated with
-xref:rgant.adoc#_rgant-Mixin[`@Mixin`]), while xref:rgcms.adoc#_rgcms_classes_uievent[UI events] can be used
+xref:../rgant/rgant.adoc#_rgant-Mixin[`@Mixin`]), while xref:../rgcms/rgcms.adoc#_rgcms_classes_uievent[UI events] can be used
 to obtain title, icons and so on.
 
 For a more complete discussion of writing JAXB view models/DTOs, see xref:ugbtb.adoc#_ugbtb_view-models[this topic]

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant_aaa_deprecated.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant_aaa_deprecated.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant_aaa_deprecated.adoc
index 47a93d7..d04be91 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant_aaa_deprecated.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant_aaa_deprecated.adoc
@@ -8,7 +8,7 @@
 As Apache Isis has evolved and grown, we found ourselves adding more and more annotations; but most of these related to either an object type (entity, view model, service) or an object member (property, collection, action).
 Over time it became harder and harder for end programmers to discover these new features.
 
-Accordingly, (in v1.8.0) we decided to unify the semantics into the main (core) annotations listed xref:rgant.adoc#_rgant-aaa_main[above].
+Accordingly, (in v1.8.0) we decided to unify the semantics into the main (core) annotations listed xref:../rgant/rgant.adoc#_rgant-aaa_main[above].
 
 The annotations listed in the table below are still supported by Apache Isis, but will be retired in Apache Isis v2.0.
 
@@ -24,126 +24,126 @@ The annotations listed in the table below are still supported by Apache Isis, bu
 
 |`@ActionOrder`
 |Order of buttons and menu items representing actions.
-|xref:rgant.adoc#_rgant-MemberOrder[`@MemberOrder`]
+|xref:../rgant/rgant.adoc#_rgant-MemberOrder[`@MemberOrder`]
 |UI
 |Yes
 
 |`@ActionInteraction`
 |Enable subscribers on the Event Bus Service to either veto, validate or take further steps before/after an action has been invoked.
-|xref:rgant.adoc#_rgant-Action_domainEvent[`@Action#domainEvent()`]
+|xref:../rgant/rgant.adoc#_rgant-Action_domainEvent[`@Action#domainEvent()`]
 |Domain
 |
 
 |`@ActionSemantics`
 |Query-only, idempotent or non-idempotent.
-|xref:rgant.adoc#_rgant-Action_semantics[`@Action#semantics()`]
+|xref:../rgant/rgant.adoc#_rgant-Action_semantics[`@Action#semantics()`]
 |Domain
 |
 
 |`@Audited`
 |Audit changes to an object.
-|xref:rgant.adoc#_rgant-DomainObject_auditing[`@DomainObject#` +
+|xref:../rgant/rgant.adoc#_rgant-DomainObject_auditing[`@DomainObject#` +
 `auditing()`]
 |Domain
 |
 
 |`@AutoComplete`
 |Repository method to search for entities
-|xref:rgant.adoc#_rgant-DomainObject_autoCompleteRepository[`@DomainObject` +
+|xref:../rgant/rgant.adoc#_rgant-DomainObject_autoCompleteRepository[`@DomainObject` +
 `#autoCompleteRepository()`]
 |UI/Domain
 |
 
 |`@Bookmarkable`
 |Whether (and how) to create a bookmark for visited object.
-|xref:rgant.adoc#_rgant-DomainObjectLayout_bookmarking[`@DomainObjectLayout` +
+|xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_bookmarking[`@DomainObjectLayout` +
 `#bookmarking()`]
 |UI
 |
 
 |`@Bounded`
 |Bounded (and limited) number of instances of an entity type, translates into a drop-down for any property of that type.
-|xref:rgant.adoc#_rgant-DomainObject_bounded[`@DomainObject#bounded()`]
+|xref:../rgant/rgant.adoc#_rgant-DomainObject_bounded[`@DomainObject#bounded()`]
 |Domain
 |
 
 |`@Bulk`
 |Indicates an action is a bulk action, can be applied to multiple instances.
-|xref:rgant.adoc#_rgant-Action_invokeOn[`@Action#invokeOn()`]
+|xref:../rgant/rgant.adoc#_rgant-Action_invokeOn[`@Action#invokeOn()`]
 |UI, Domain
 |
 
 |`@CollectionInteraction`
 |Enable subscribers on the Event Bus Service to either veto, validate or take further steps before/after a collection has been added to or removed from.
-|xref:rgant.adoc#_rgant-Collection_domainEvent[`@Collection#domainEvent()`]
+|xref:../rgant/rgant.adoc#_rgant-Collection_domainEvent[`@Collection#domainEvent()`]
 |Domain
 |
 
 |`@Command`
 |Action invocation should be reified as a command object, optionally persistable for profiling and enhanced auditing, and background/async support.
-|xref:rgant.adoc#_rgant-Action_command[`@Action#command()`]
+|xref:../rgant/rgant.adoc#_rgant-Action_command[`@Action#command()`]
 |Domain
 |
 
 |`@CssClass`
 |Allow visual representation of individual objects or object members layout to be customized by application-specific CSS.
-|`#cssClass()` attribute for: xref:rgant.adoc#_rgant-DomainObjectLayout_cssClass[`@DomainObjectLayout`], xref:rgant.adoc#_rgant-PropertyLayout_cssClass[`@PropertyLayout`],  xref:rgant.adoc#_rgant-CollectionLayout_cssClass[`@CollectionLayout`], xref:rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout`] and xref:rgant.adoc#_rgant-ParameterLayout_cssClass[`@ParameterLayout`]
+|`#cssClass()` attribute for: xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_cssClass[`@DomainObjectLayout`], xref:../rgant/rgant.adoc#_rgant-PropertyLayout_cssClass[`@PropertyLayout`],  xref:../rgant/rgant.adoc#_rgant-CollectionLayout_cssClass[`@CollectionLayout`], xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout`] and xref:../rgant/rgant.adoc#_rgant-ParameterLayout_cssClass[`@ParameterLayout`]
 |UI
 |Yes
 
 |`@CssClassFa`
 |So that font awesome icons can be applied to action buttons/menu items and optionally as an object icon.
-|`cssClassFa()` attribute for: xref:rgant.adoc#_rgant-ActionLayout_cssClassFa[`@ActionLayout`], xref:rgant.adoc#_rgant-DomainObjectLayout_cssClassFa[`DomainObjectLayout`] and xref:rgant.adoc#_rgant-ViewModelLayout_cssClassFa[`ViewModelLayout`]
+|`cssClassFa()` attribute for: xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClassFa[`@ActionLayout`], xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_cssClassFa[`DomainObjectLayout`] and xref:../rgant/rgant.adoc#_rgant-ViewModelLayout_cssClassFa[`ViewModelLayout`]
 |UI
 |Yes
 
 |`@Debug`
 |Action only invokable in debug mode.
-|Not supported by either the xref:ugvw.adoc#[Wicket viewer] or the xref:ugvro.adoc#[RestfulObjects viewer]; use prototype mode instead (xref:rgant.adoc#_rgant-Action_restrictTo[`@Action#restrictTo()`])
+|Not supported by either the xref:ugvw.adoc#[Wicket viewer] or the xref:ugvro.adoc#[RestfulObjects viewer]; use prototype mode instead (xref:../rgant/rgant.adoc#_rgant-Action_restrictTo[`@Action#restrictTo()`])
 |UI
 |
 
 |`@DescribedAs`
 |Provide a longer description/tool-tip of an object or object member.
-|`#describedAs()` attribute for xref:rgant.adoc#_rgant-DomainObject_describedAs[`@DomainObjectLayout`], xref:rgant.adoc#_rgant-PropertyLayout_describedAs[`@PropertyLayout`], xref:rgant.adoc#_rgant-CollectionLayout_describedAs[`@CollectionLayout`], xref:rgant.adoc#_rgant-ActionLayout_describedAs[`@ActionLayout`] and xref:rgant.adoc#_rgant-ParameterLayout_describedAs[`@ParameterLayout`]
+|`#describedAs()` attribute for xref:../rgant/rgant.adoc#_rgant-DomainObject_describedAs[`@DomainObjectLayout`], xref:../rgant/rgant.adoc#_rgant-PropertyLayout_describedAs[`@PropertyLayout`], xref:../rgant/rgant.adoc#_rgant-CollectionLayout_describedAs[`@CollectionLayout`], xref:../rgant/rgant.adoc#_rgant-ActionLayout_describedAs[`@ActionLayout`] and xref:../rgant/rgant.adoc#_rgant-ParameterLayout_describedAs[`@ParameterLayout`]
 |UI
 |Yes
 
 |`@Disabled`
 |Object property cannot be edited, an object collection cannot be added to/removed from, or an object action cannot be invoked.
-|`#editing()` attribute for xref:rgant.adoc#_rgant-Property_editing[`@Property`],  xref:rgant.adoc#_rgant-Collection_editing[`@Collection`] and xref:rgant.adoc#_rgant-DomainObject_editing[`@DomainObject`]
+|`#editing()` attribute for xref:../rgant/rgant.adoc#_rgant-Property_editing[`@Property`],  xref:../rgant/rgant.adoc#_rgant-Collection_editing[`@Collection`] and xref:../rgant/rgant.adoc#_rgant-DomainObject_editing[`@DomainObject`]
 |UI, Domain
 |Yes
 
 |`@Exploration`
 |Action available in special 'exploration' mode.
-|Not supported by either the xref:ugvw.adoc#[Wicket viewer] or the xref:ugvro.adoc#[RestfulObjects viewer]; use prototype mode instead (xref:rgant.adoc#_rgant-Action_restrictTo[`@Action#restrictTo()`])
+|Not supported by either the xref:ugvw.adoc#[Wicket viewer] or the xref:ugvro.adoc#[RestfulObjects viewer]; use prototype mode instead (xref:../rgant/rgant.adoc#_rgant-Action_restrictTo[`@Action#restrictTo()`])
 |UI
 |
 
 |`@FieldOrder`
 |Order of properties and collections.
-|xref:rgant.adoc#_rgant-MemberOrder[`@MemberOrder`]
+|xref:../rgant/rgant.adoc#_rgant-MemberOrder[`@MemberOrder`]
 |UI
 |Yes
 
 |`@Hidden`
 |Object member is not visible, or on domain service (to indicate that none of its actions are visible).
-|For domain object members, use `#hidden()` attribute of xref:rgant.adoc#_rgant-Action_hidden[`Action`], xref:rgant.adoc#_rgant-Property_hidden[`Property`] or xref:rgant.adoc#_rgant-Collection_hidden[`Collection`].  +
-For domain service, use xref:rgant.adoc#_rgant-DomainService_nature[`@DomainService(` +
+|For domain object members, use `#hidden()` attribute of xref:../rgant/rgant.adoc#_rgant-Action_hidden[`Action`], xref:../rgant/rgant.adoc#_rgant-Property_hidden[`Property`] or xref:../rgant/rgant.adoc#_rgant-Collection_hidden[`Collection`].  +
+For domain service, use xref:../rgant/rgant.adoc#_rgant-DomainService_nature[`@DomainService(` +
 `nature=DOMAIN)`]
 |UI, Domain
 |Yes
 
 |`@Idempotent`
 |Whether an action is idempotent (can be invoked multiple times with same post-condition).
-|xref:rgant.adoc#_rgant-Action_semantics[`@Action#semantics`]
+|xref:../rgant/rgant.adoc#_rgant-Action_semantics[`@Action#semantics`]
 |Domain
 |
 
 |`@Ignore`
 |Exclude this method from the metamodel.
-|xref:rgant.adoc#_rgant-Programmatic[`@Programmatic`]. +
+|xref:../rgant/rgant.adoc#_rgant-Programmatic[`@Programmatic`]. +
 
 `@Ignore` was deprecated because it can easily clash with `@org.junit.Ignore`.
 |Domain
@@ -152,7 +152,7 @@ For domain service, use xref:rgant.adoc#_rgant-DomainService_nature[`@DomainServ
 |`@Immutable`
 |An object's state cannot be changed (properties cannot be edited, collections cannot be added to or removed from).
 Actions can still be invoked.
-|xref:rgant.adoc#_rgant-DomainObject_editing[`@DomainObject#editing()`]
+|xref:../rgant/rgant.adoc#_rgant-DomainObject_editing[`@DomainObject#editing()`]
 |Domain
 |
 
@@ -164,7 +164,7 @@ Actions can still be invoked.
 
 |`@MaxLength`
 |Maximum length of a property value (strings).
-|`#maxLength()` attribute for xref:rgant.adoc#_rgant-Property_maxLength[`@Property`] or xref:rgant.adoc#_rgant-Parameter_maxLength[`@Parameter`]
+|`#maxLength()` attribute for xref:../rgant/rgant.adoc#_rgant-Property_maxLength[`@Property`] or xref:../rgant/rgant.adoc#_rgant-Parameter_maxLength[`@Parameter`]
 |Domain
 |
 
@@ -183,65 +183,65 @@ Actions can still be invoked.
 
 |`@MultiLine`
 |Render string property over multiple lines (a textarea rather than a textbox).
-|`#multiLine()` attribute for xref:rgant.adoc#_rgant-Property_multiLine[`@Property`] or xref:rgant.adoc#_rgant-Parameter_multiLine[`@Parameter`]
+|`#multiLine()` attribute for xref:../rgant/rgant.adoc#_rgant-Property_multiLine[`@Property`] or xref:../rgant/rgant.adoc#_rgant-Parameter_multiLine[`@Parameter`]
 |UI
 |Yes
 
 |`@MustSatisfy`
 |Specify arbitrary specification constraints on a property or action parameter.
-|`#mustSatisfy()` attribute for xref:rgant.adoc#_rgant-Property_mustSatisfy[`@Property`] or xref:rgant.adoc#_rgant-Parameter_mustSatisfy[`@Parameter`]
+|`#mustSatisfy()` attribute for xref:../rgant/rgant.adoc#_rgant-Property_mustSatisfy[`@Property`] or xref:../rgant/rgant.adoc#_rgant-Parameter_mustSatisfy[`@Parameter`]
 |Domain
 |
 
 |`@Named`
 |Override name inferred from class. Required for parameter names (prior to Java8).
-|`#named()` attribute for xref:rgant.adoc#_rgant-DomainServiceLayout_named[`@DomainServiceLayout`], xref:rgant.adoc#_rgant-DomainObjectLayout_named[`@DomainObjectLayout`], xref:rgant.adoc#_rgant-PropertyLayout_named[`@PropertyLayout`], xref:rgant.adoc#_rgant-CollectionLayout_named[`@CollectionLayout`], xref:rgant.adoc#_rgant-ActionLayout_named[`@ActionLayout`] and xref:rgant.adoc#_rgant-ParameterLayout_named[`@ParameterLayout`]
+|`#named()` attribute for xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_named[`@DomainServiceLayout`], xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_named[`@DomainObjectLayout`], xref:../rgant/rgant.adoc#_rgant-PropertyLayout_named[`@PropertyLayout`], xref:../rgant/rgant.adoc#_rgant-CollectionLayout_named[`@CollectionLayout`], xref:../rgant/rgant.adoc#_rgant-ActionLayout_named[`@ActionLayout`] and xref:../rgant/rgant.adoc#_rgant-ParameterLayout_named[`@ParameterLayout`]
 |UI
 |Yes
 
 |`@NotContributed`
 |Indicates that a domain service action is not rendered as an action on the (entity) types of its parameters.
 For 1-arg query-only actions, controls whether the domain service action is rendered as a property or collection on the entity type of its parameter.
-|Use xref:rgant.adoc#_rgant-DomainService_nature[`@DomainService#nature()`] to specify whether any of the actions in a domain service should appear in the menu bars (applies at type level, not action level).
-For individual actions, use xref:rgant.adoc#_rgant-ActionLayout_contributedAs[`@ActionLayout#` +
+|Use xref:../rgant/rgant.adoc#_rgant-DomainService_nature[`@DomainService#nature()`] to specify whether any of the actions in a domain service should appear in the menu bars (applies at type level, not action level).
+For individual actions, use xref:../rgant/rgant.adoc#_rgant-ActionLayout_contributedAs[`@ActionLayout#` +
 `contributedAs()`] to specify whether any individual action should be contributed only as an action or as an association (property or collection).
 |UI
 |
 
 |`@NotInServiceMenu`
 |Indicates that a domain service should not be rendered in the application menu (at top of page in Wicket viewer).
-|xref:rgant.adoc#_rgant-DomainService_nature[`@DomainService#nature()`] to signify that none of the actions in a domain service should appear in the menu bars
+|xref:../rgant/rgant.adoc#_rgant-DomainService_nature[`@DomainService#nature()`] to signify that none of the actions in a domain service should appear in the menu bars
 |UI
 |
 
 |`@NotPersisted`
 |Indicates that an object property is not persisted (meaning it is excluded from view model mementos, and should not be audited).
-|`#notPersisted()` attribute of xref:rgant.adoc#_rgant-Property_notPersisted[`@Property`] and xref:rgant.adoc#_rgant-Collection_notPersisted[`@Collection`]
+|`#notPersisted()` attribute of xref:../rgant/rgant.adoc#_rgant-Property_notPersisted[`@Property`] and xref:../rgant/rgant.adoc#_rgant-Collection_notPersisted[`@Collection`]
 |Domain, Persistence
 |
 
 |`@ObjectType`
 |For constructing the external identifier (URI) of an entity instance (part of its URL in both Wicket viewer and Restful Objects viewer).
 Also part of the toString representation of bookmarks, if using the Bookmark Service
-|xref:rgant.adoc#_rgant-DomainObject_objectType[`@DomainObject#objectType()`]
+|xref:../rgant/rgant.adoc#_rgant-DomainObject_objectType[`@DomainObject#objectType()`]
 |Domain
 |
 
 |`@Optional`
 |Specifies that a property or action parameter is not mandatory.
-|`#optionality()` attribute for xref:rgant.adoc#_rgant-Property_optionality[`@Property`] or  xref:rgant.adoc#_rgant-Parameter_optionality[`@Parameter`]
+|`#optionality()` attribute for xref:../rgant/rgant.adoc#_rgant-Property_optionality[`@Property`] or  xref:../rgant/rgant.adoc#_rgant-Parameter_optionality[`@Parameter`]
 |Domain
 |
 
 |`@Paged`
 |Number of instances to display in tables representing (standalone or parented) collections.
-|`#paged()` attribute for xref:rgant.adoc#_rgant-DomainObjectLayout_paged[`@DomainObjectLayout`] or xref:rgant.adoc#_rgant-CollectionLayout_paged[`@CollectionLayout`]
+|`#paged()` attribute for xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_paged[`@DomainObjectLayout`] or xref:../rgant/rgant.adoc#_rgant-CollectionLayout_paged[`@CollectionLayout`]
 |UI
 |Yes
 
 |`@Plural`
 |For the irregular plural form of an entity type.
-|xref:rgant.adoc#_rgant-DomainObject_plural[`@DomainObjectLayout` +
+|xref:../rgant/rgant.adoc#_rgant-DomainObject_plural[`@DomainObjectLayout` +
 `#plural()`]
 |UI
 |
@@ -249,103 +249,103 @@ Also part of the toString representation of bookmarks, if using the Bookmark Ser
 |`@PostsAction` +
 `InvokedEvent`
 |Post a domain event to the Event Bus Service indicating that an action has been invoked.
-|xref:rgant.adoc#_rgant-Action_domainEvent[`@Action#domainEvent()`]
+|xref:../rgant/rgant.adoc#_rgant-Action_domainEvent[`@Action#domainEvent()`]
 |Domain
 |
 
 |`@PostsCollection` +
 `AddedToEvent`
 |Post a domain event to the Event Bus Service indicating that an element has been added to a collection.
-|xref:rgant.adoc#_rgant-Collection_domainEvent[`@Collection#domainEvent()`]
+|xref:../rgant/rgant.adoc#_rgant-Collection_domainEvent[`@Collection#domainEvent()`]
 |Domain
 |
 
 |`@PostsCollection` +
 `RemovedFromEvent`
 |Post a domain event to the Event Bus Service indicating that an element has been removed from a collection.
-|xref:rgant.adoc#_rgant-Collection_domainEvent[`@Collection#domainEvent()`]
+|xref:../rgant/rgant.adoc#_rgant-Collection_domainEvent[`@Collection#domainEvent()`]
 |Domain
 |
 
 |`@PostsProperty` +
 `ChangedEvent`
 |Post a domain event to the Event Bus Service indicating that the value of a property has changed.
-|xref:rgant.adoc#_rgant-Property_domainEvent[`@Property#domainEvent()`]
+|xref:../rgant/rgant.adoc#_rgant-Property_domainEvent[`@Property#domainEvent()`]
 |Domain
 |
 
 |`@PropertyInteraction`
 |Enable subscribers on the Event Bus Service to either veto, validate or take further steps before/after a property has been modified or cleared.
-|xref:rgant.adoc#_rgant-Property_domainEvent[`@Property#domainEvent()`]
+|xref:../rgant/rgant.adoc#_rgant-Property_domainEvent[`@Property#domainEvent()`]
 |Domain
 |
 
 |`@Prototype`
 |Indicates that an action should only be visible in 'prototype' mode.
-|xref:rgant.adoc#_rgant-Action_restrictTo[`@Action#restrictTo()`]
+|xref:../rgant/rgant.adoc#_rgant-Action_restrictTo[`@Action#restrictTo()`]
 |UI
 |Yes
 
 |`@PublishedAction`
 |Action invocation should be serialized and published by configured PublishingService (if any), eg to other systems.
-|xref:rgant.adoc#_rgant-Action_publishing[`@Action#publishing()`]
+|xref:../rgant/rgant.adoc#_rgant-Action_publishing[`@Action#publishing()`]
 |Domain
 |
 
 |`@PublishedObject`
 |Change to object should be serialized and published by configured PublishingService (if any), eg to other systems.
-|xref:rgant.adoc#_rgant-DomainObject_publishing[`@DomainObject#publishing()`]
+|xref:../rgant/rgant.adoc#_rgant-DomainObject_publishing[`@DomainObject#publishing()`]
 |Domain
 |
 
 |`@QueryOnly`
 |Whether an action is query-only (has no side-effects).
-|xref:rgant.adoc#_rgant-Action_semantics[`@Action#semantics()`]
+|xref:../rgant/rgant.adoc#_rgant-Action_semantics[`@Action#semantics()`]
 |Domain
 |
 
 |`@RegEx`
 |Validate change to value of string property.
-|`#regexPattern()` for xref:rgant.adoc#_rgant-Property_regexPattern[`@Property`] or  xref:rgant.adoc#_rgant-Property_regexPattern[`@Parameter`].
+|`#regexPattern()` for xref:../rgant/rgant.adoc#_rgant-Property_regexPattern[`@Property`] or  xref:../rgant/rgant.adoc#_rgant-Property_regexPattern[`@Parameter`].
 |Domain
 |
 
 |`@Render`
 |Eagerly (or lazily) render the contents of a collection.
-|xref:rgant.adoc#_rgant-CollectionLayout_render[`@CollectionLayout` +
+|xref:../rgant/rgant.adoc#_rgant-CollectionLayout_render[`@CollectionLayout` +
 `#render()`]
 |UI
 |Yes
 
 |`@RenderedAsDayBefore`
 |Render dates as the day before; ie store [a,b) internally but render [a,b-1]) to end-user.
-|`#renderedAsDayBefore()` attribute for xref:rgant.adoc#_rgant-PropertyLayout_renderedAsDayBefore[`@PropertyLayout`] and xref:rgant.adoc#_rgant-ParameterLayout_renderedAsDayBefore[`@ParameterLayout`].
+|`#renderedAsDayBefore()` attribute for xref:../rgant/rgant.adoc#_rgant-PropertyLayout_renderedAsDayBefore[`@PropertyLayout`] and xref:../rgant/rgant.adoc#_rgant-ParameterLayout_renderedAsDayBefore[`@ParameterLayout`].
 |UI
 |
 
 |`@Resolve`
 |Eagerly (or lazily) render the contents of a collection (same as `@Render)`
-|xref:rgant.adoc#_rgant-CollectionLayout_render[`@CollectionLayout` +
+|xref:../rgant/rgant.adoc#_rgant-CollectionLayout_render[`@CollectionLayout` +
 `#render()`]
 |UI
 |Yes
 
 |`@SortedBy`
 |Display instances in collections in the order determined by the provided Comparator.
-|xref:rgant.adoc#_rgant-CollectionLayout_sortedBy[`@CollectionLayout` +
+|xref:../rgant/rgant.adoc#_rgant-CollectionLayout_sortedBy[`@CollectionLayout` +
 `#sortedBy()`]
 |UI
 |Yes
 
 |`@TypeOf`
 |The type of entity stored within a collection, or as the result of invoking an action, if cannot be otherwise inferred, eg from generics.
-|`#typeOf()` attribute for xref:rgant.adoc#_rgant-Collection_typeOf[`@Collection`] and xref:rgant.adoc#_rgant-Action_typeOf[`@Action`]
+|`#typeOf()` attribute for xref:../rgant/rgant.adoc#_rgant-Collection_typeOf[`@Collection`] and xref:../rgant/rgant.adoc#_rgant-Action_typeOf[`@Action`]
 |Domain
 |
 
 |`@TypicalLength`
 |The typical length of a string property, eg to determine a sensible length for a textbox.
-|`#typicalLength()` attribute for xref:rgant.adoc#_rgant-PropertyLayout_typicalLength[`@PropertyLayout`] and xref:rgant.adoc#_rgant-ParameterLayout_typicalLength[`@ParameterLayout`]
+|`#typicalLength()` attribute for xref:../rgant/rgant.adoc#_rgant-PropertyLayout_typicalLength[`@PropertyLayout`] and xref:../rgant/rgant.adoc#_rgant-ParameterLayout_typicalLength[`@ParameterLayout`]
 |UI
 |Yes
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant_aaa_jdo.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant_aaa_jdo.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant_aaa_jdo.adoc
index 8502406..7c40b21 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant_aaa_jdo.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant_aaa_jdo.adoc
@@ -26,7 +26,7 @@ The table below lists the JDO annotations currently recognized by Apache Isis.
 |Applies to
 
 
-|xref:rgant.adoc#_rgant-Column[`@javax.jdo.annotations.` +
+|xref:../rgant/rgant.adoc#_rgant-Column[`@javax.jdo.annotations.` +
 `Column`]
 |Used to determine whether a property is mandatory or optional.  For `String` and `BigDecimal` properties, used to determine length/precision/scale.
 
@@ -34,16 +34,16 @@ The table below lists the JDO annotations currently recognized by Apache Isis.
 |Property
 
 
-|xref:rgant.adoc#_rgant-Discriminator[`@javax.jdo.annotations.` +
+|xref:../rgant/rgant.adoc#_rgant-Discriminator[`@javax.jdo.annotations.` +
 `Discriminator`]
 |Override for the object type, as used in `Bookmark`s, URLs for xref:ugvro.adoc#[RestfulObjects viewer] and elsewhere. +
 
-Note that the discriminator overrides the object type that may otherwise be inferred from the xref:rgant.adoc#_rgant-PersistenceCapable[`@PersistenceCapable`] annotation.
+Note that the discriminator overrides the object type that may otherwise be inferred from the xref:../rgant/rgant.adoc#_rgant-PersistenceCapable[`@PersistenceCapable`] annotation.
 |Domain / persistence
 |Class
 
 
-|xref:rgant.adoc#_rgant-NotPersistent[`@javax.jdo.annotations.` +
+|xref:../rgant/rgant.adoc#_rgant-NotPersistent[`@javax.jdo.annotations.` +
 `NotPersistent`]
 |Used to determine whether to enforce or skip some xref:ugbtb.adoc#_ugbtb_programming-model_custom-validator[metamodel validation] for `@Column` versus equivalent Isis annotations.
 
@@ -52,17 +52,17 @@ Note that the discriminator overrides the object type that may otherwise be infe
 
 
 
-|xref:rgant.adoc#_rgant-PersistenceCapable[`@javax.jdo.annotations.` +
+|xref:../rgant/rgant.adoc#_rgant-PersistenceCapable[`@javax.jdo.annotations.` +
 `PersistenceCapable`]
 |Used to build Apache Isis' own internal identifier for objects. +
 
-If the `schema()` attribute is specified (and if xref:rgant.adoc#_rgant-Discriminator[`@Discriminator`] _hasn't_ been specified), is also used to derive the object type, as used in `Bookmark`s, URLs for xref:ugvro.adoc#[RestfulObjects viewer] and elsewhere.
+If the `schema()` attribute is specified (and if xref:../rgant/rgant.adoc#_rgant-Discriminator[`@Discriminator`] _hasn't_ been specified), is also used to derive the object type, as used in `Bookmark`s, URLs for xref:ugvro.adoc#[RestfulObjects viewer] and elsewhere.
 
 |Domain / persistence
 |Class
 
 
-|xref:rgant.adoc#_rgant-PrimaryKey[`@javax.jdo.annotations.` +
+|xref:../rgant/rgant.adoc#_rgant-PrimaryKey[`@javax.jdo.annotations.` +
 `PrimaryKey`]
 |Used to ensure Apache Isis does not overwrite application-defined primary keys, and to ensure is read-only in the UI.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant_aaa_jee.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant_aaa_jee.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant_aaa_jee.adoc
index 42e1a96..5435a7b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant_aaa_jee.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant_aaa_jee.adoc
@@ -18,57 +18,57 @@ The table below lists the JEE annotations currently recognized.  Expect to see m
 |Layer
 |xref:ugvw.adoc#_ugvw_layout_file-based[File-based layout]?
 
-|xref:rgant.adoc#_rgant-Digits[`@javax.validation.` +
+|xref:../rgant/rgant.adoc#_rgant-Digits[`@javax.validation.` +
 `constraints.` +
 `Digits`]
 |Precision/scale for BigDecimal values.
 |Domain
 |
 
-|xref:rgant.adoc#_rgant-Inject[`@javax.inject.` +
+|xref:../rgant/rgant.adoc#_rgant-Inject[`@javax.inject.` +
 `Inject`]
 |Inject domain service into a domain object (entity or view model) or another domain service.
 |Domain
 |
 
-|xref:rgant.adoc#_rgant-Digits[`@javax.annotation.` +
+|xref:../rgant/rgant.adoc#_rgant-Digits[`@javax.annotation.` +
 `Nullable`]
 |Specify that a property/parameter is optional.
 |Domain
 |
 
-|xref:rgant.adoc#_rgant-PostConstruct[`@javax.annotation.` +
+|xref:../rgant/rgant.adoc#_rgant-PostConstruct[`@javax.annotation.` +
 `PostConstruct`]
-|Callback for domain services (either singleton or xref:rgant.adoc#_rgant-RequestScoped[request-scoped]) to initialize themselves once instantiated.
+|Callback for domain services (either singleton or xref:../rgant/rgant.adoc#_rgant-RequestScoped[request-scoped]) to initialize themselves once instantiated.
 
 |Domain
 |
 
-|xref:rgant.adoc#_rgant-PreDestroy[`@javax.annotation.` +
+|xref:../rgant/rgant.adoc#_rgant-PreDestroy[`@javax.annotation.` +
 `PreDestroy`]
-|Callback for domain services (either singleton or xref:rgant.adoc#_rgant-RequestScoped[request-scoped]) to clean up resources prior to destruction.
+|Callback for domain services (either singleton or xref:../rgant/rgant.adoc#_rgant-RequestScoped[request-scoped]) to clean up resources prior to destruction.
 
 |Domain
 |
 
-|xref:rgant.adoc#_rgant-RequestScoped[`@javax.enterprise.` +
+|xref:../rgant/rgant.adoc#_rgant-RequestScoped[`@javax.enterprise.` +
 `context.` +
 `RequestScoped`]
 |Specify that a domain service has request-scope (rather than a singleton).
 |Domain
 |
 
-|xref:rgant.adoc#_rgant-XmlRootElement[`javax.xml.bind` +
+|xref:../rgant/rgant.adoc#_rgant-XmlRootElement[`javax.xml.bind` +
 `.annotation` +
 `XmlRootElement`]
 |JAXB annotation indicating the XML root element when serialized to XML; also used by the framework for view models (whose memento is the XML), often also acting as a DTO.
 |Application
 |
 
-|xref:rgant.adoc#_rgant-XmlJavaTypeAdapter[`javax.xml.bind` +
+|xref:../rgant/rgant.adoc#_rgant-XmlJavaTypeAdapter[`javax.xml.bind` +
 `.annotation` +
 `XmlJavaTypeAdapter`]
-|JAXB annotation defining how to serialize an entity.  Used in conjunction with the (framework provided) `PersistentEntityAdapter` class to serialize persistent entities into a canonical OID (equivalent to the `Bookmark` provided by the xref:rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`]).
+|JAXB annotation defining how to serialize an entity.  Used in conjunction with the (framework provided) `PersistentEntityAdapter` class to serialize persistent entities into a canonical OID (equivalent to the `Bookmark` provided by the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`]).
 |Domain
 |
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant_aaa_main.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant_aaa_main.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant_aaa_main.adoc
index 7b4bd8b..26e6530 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant_aaa_main.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant_aaa_main.adoc
@@ -26,72 +26,72 @@ The table below summarizes these most commonly used annotations in Apache Isis.
 |Layer
 |xref:ugvw.adoc#_ugvw_layout_file-based[File-based layout]?
 
-|xref:rgant.adoc#_rgant-Action[`@Action`]
+|xref:../rgant/rgant.adoc#_rgant-Action[`@Action`]
 |Domain semantics for actions
 |Domain
 |
 
-|xref:rgant.adoc#_rgant-ActionLayout[`@ActionLayout`]
+|xref:../rgant/rgant.adoc#_rgant-ActionLayout[`@ActionLayout`]
 |User interface hints for actions
 |UI
 |Yes
 
-|xref:rgant.adoc#_rgant-Collection[`@Collection`]
+|xref:../rgant/rgant.adoc#_rgant-Collection[`@Collection`]
 |Domain semantics for collections
 |Domain
 |
 
-|xref:rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`]
+|xref:../rgant/rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`]
 |User interface hints for collections
 |UI
 |Yes
 
-|xref:rgant.adoc#_rgant-DomainObject[`@DomainObject`]
+|xref:../rgant/rgant.adoc#_rgant-DomainObject[`@DomainObject`]
 |Domain semantics for domain object (entities and optionally view models, see also `@ViewModel)`
 |Domain
 |
 
-|xref:rgant.adoc#_rgant-DomainObjectLayout[`@DomainObjectLayout`]
+|xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout[`@DomainObjectLayout`]
 |User interface hints for domain object (entities and optionally view models, see also `@ViewModelLayout)`
 |UI
 |Yes
 
-|xref:rgant.adoc#_rgant-DomainService[`@DomainService`]
+|xref:../rgant/rgant.adoc#_rgant-DomainService[`@DomainService`]
 |Class is a domain service (rather than an entity or view model)
 |Domain
 |
 
-|xref:rgant.adoc#_rgant-DomainServiceLayout[`@DomainServiceLayout`]
+|xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout[`@DomainServiceLayout`]
 |User interface hints for domain services
 |UI
 |
 
-|xref:rgant.adoc#_rgant-Parameter[`@Parameter`]
+|xref:../rgant/rgant.adoc#_rgant-Parameter[`@Parameter`]
 |Domain semantics for action parameters
 |Domain
 |
 
-|xref:rgant.adoc#_rgant-ParameterLayout[`@ParameterLayout`]
+|xref:../rgant/rgant.adoc#_rgant-ParameterLayout[`@ParameterLayout`]
 |Layout hints for an action parameter (currently: its label position either to top or the left).
 |UI
 |Yes
 
-|xref:rgant.adoc#_rgant-Property[`@Property`]
+|xref:../rgant/rgant.adoc#_rgant-Property[`@Property`]
 |Domain semantics for properties
 |Domain
 |
 
-|xref:rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`]
+|xref:../rgant/rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`]
 |Layout hints for a property
 |UI
 |Yes
 
-|xref:rgant.adoc#_rgant-ViewModel[`@ViewModel`]
+|xref:../rgant/rgant.adoc#_rgant-ViewModel[`@ViewModel`]
 |Specify that a class is a view model (as opposed to an entity or domain service); equivalent to `@DomainObject(nature`=VIEW_MODEL).
 |Domain, Persistence
 |
 
-|xref:rgant.adoc#_rgant-ViewModelLayout[`@ViewModelLayout`]
+|xref:../rgant/rgant.adoc#_rgant-ViewModelLayout[`@ViewModelLayout`]
 |User interface hints for view models.
 For use with `@ViewModel`. If specifying view models using `@DomainObject(nature=VIEW_MODEL)` then use `@DomainObjectLayout`)
 |UI

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant_aaa_other.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant_aaa_other.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant_aaa_other.adoc
index 30ecad9..db3a31a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant_aaa_other.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant_aaa_other.adoc
@@ -15,34 +15,34 @@ These annotations are also commonly used, but relate _not_ to objects or object
 |Layer
 |xref:ugvw.adoc#_ugvw_layout_file-based[File-based layout]?
 
-|xref:rgant.adoc#_rgant-Facets[`@Facets`]
+|xref:../rgant/rgant.adoc#_rgant-Facets[`@Facets`]
 |Install arbitrary facets within the Apache Isis metamodel.
 |(any)
 |
 
-|xref:rgant.adoc#_rgant-HomePage[`@HomePage`]
+|xref:../rgant/rgant.adoc#_rgant-HomePage[`@HomePage`]
 |Query-only action (on domain service) to be invoked, result of which is rendered as the user's home page.
 |UI
 |
 
-|xref:rgant.adoc#_rgant-MemberOrder[`@MemberOrder`]
+|xref:../rgant/rgant.adoc#_rgant-MemberOrder[`@MemberOrder`]
 |Ordering of properties, collections and actions, and also associating actions with either a property or a collection.
 |UI
 |Yes
 
 
-|xref:rgant.adoc#_rgant-MinLength[`@MinLength`]
+|xref:../rgant/rgant.adoc#_rgant-MinLength[`@MinLength`]
 |Minimum number of characters required for an auto-complete search argument.
 |UI
 |
 
 
-|xref:rgant.adoc#_rgant-Programmatic[`@Programmatic`]
+|xref:../rgant/rgant.adoc#_rgant-Programmatic[`@Programmatic`]
 |Ignore a public method, excluded from the Apache Isis metamodel.
 |Domain
 |
 
-|xref:rgant.adoc#_rgant-Title[`@Title`]
+|xref:../rgant/rgant.adoc#_rgant-Title[`@Title`]
 |Indicates which of the object's properties should be used to build up a title for the object.
 |UI
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcfg/_rgcfg_configuring-core.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcfg/_rgcfg_configuring-core.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcfg/_rgcfg_configuring-core.adoc
index 621d8c5..bd72906 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcfg/_rgcfg_configuring-core.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcfg/_rgcfg_configuring-core.adoc
@@ -29,21 +29,21 @@ Configuration properties for the JDO/DataNucleus objectstore can be found in the
 `domainEvent.postForDefault`
 |`true`,`false` +
 (`true`)
-|Whether an event should be posted if xref:rgant.adoc#_rgant-Action_domainEvent[`@Action#domainEvent()`] is not specified (is set to `ActionDomainEvent.Default`).
+|Whether an event should be posted if xref:../rgant/rgant.adoc#_rgant-Action_domainEvent[`@Action#domainEvent()`] is not specified (is set to `ActionDomainEvent.Default`).
 
 |`isis.reflector.facet.` +
 `collectionAnnotation.` +
 `domainEvent.postForDefault`
 |`true`,`false` +
 (`true`)
-|Whether an event should be posted if xref:rgant.adoc#_rgant-Collection_domainEvent[`@Collection#domainEvent()`] is not specified (is set to `CollectionDomainEvent.Default`).
+|Whether an event should be posted if xref:../rgant/rgant.adoc#_rgant-Collection_domainEvent[`@Collection#domainEvent()`] is not specified (is set to `CollectionDomainEvent.Default`).
 
 |`isis.reflector.facet.` +
 `propertyAnnotation.` +
 `domainEvent.postForDefault`
 |`true`,`false` +
 (`true`)
-|Whether an event should be posted if xref:rgant.adoc#_rgant-Property_domainEvent[`@Property#domainEvent()`] is not specified (is set to `PropertyDomainEvent.Default`).
+|Whether an event should be posted if xref:../rgant/rgant.adoc#_rgant-Property_domainEvent[`@Property#domainEvent()`] is not specified (is set to `PropertyDomainEvent.Default`).
 
 
 
@@ -70,7 +70,7 @@ Configuration properties for the JDO/DataNucleus objectstore can be found in the
 `postForDefault`
 |`true`,`false` +
 (`true`)
-|Whether an event should be posted if xref:rgant.adoc#_rgant-DomainObject_createdLifecycleEvent[`@DomainObject#createdLifecycleEvent()`] is not specified (is set to `ObjectCreatedEvent.Default`).
+|Whether an event should be posted if xref:../rgant/rgant.adoc#_rgant-DomainObject_createdLifecycleEvent[`@DomainObject#createdLifecycleEvent()`] is not specified (is set to `ObjectCreatedEvent.Default`).
 
 |`isis.reflector.facet.` +
 `domainObjectAnnotation.` +
@@ -78,7 +78,7 @@ Configuration properties for the JDO/DataNucleus objectstore can be found in the
 `postForDefault`
 |`true`,`false` +
 (`true`)
-|Whether an event should be posted if xref:rgant.adoc#_rgant-DomainObject_loadedLifecycleEvent[`@DomainObject#loadedLifecycleEvent()`] is not specified (is set to `ObjectLoadedEvent.Default`).
+|Whether an event should be posted if xref:../rgant/rgant.adoc#_rgant-DomainObject_loadedLifecycleEvent[`@DomainObject#loadedLifecycleEvent()`] is not specified (is set to `ObjectLoadedEvent.Default`).
 
 |`isis.reflector.facet.` +
 `domainObjectAnnotation.` +
@@ -86,7 +86,7 @@ Configuration properties for the JDO/DataNucleus objectstore can be found in the
 `postForDefault`
 |`true`,`false` +
 (`true`)
-|Whether an event should be posted if xref:rgant.adoc#_rgant-DomainObject_persistingLifecycleEvent[`@DomainObject#persistingLifecycleEvent()`] is not specified (is set to `ObjectPersistingEvent.Default`).
+|Whether an event should be posted if xref:../rgant/rgant.adoc#_rgant-DomainObject_persistingLifecycleEvent[`@DomainObject#persistingLifecycleEvent()`] is not specified (is set to `ObjectPersistingEvent.Default`).
 
 |`isis.reflector.facet.` +
 `domainObjectAnnotation.` +
@@ -94,7 +94,7 @@ Configuration properties for the JDO/DataNucleus objectstore can be found in the
 `postForDefault`
 |`true`,`false` +
 (`true`)
-|Whether an event should be posted if xref:rgant.adoc#_rgant-DomainObject_persistedLifecycleEvent[`@DomainObject#persistedLifecycleEvent()`] is not specified (is set to `ObjectPersistedEvent.Default`).
+|Whether an event should be posted if xref:../rgant/rgant.adoc#_rgant-DomainObject_persistedLifecycleEvent[`@DomainObject#persistedLifecycleEvent()`] is not specified (is set to `ObjectPersistedEvent.Default`).
 
 |`isis.reflector.facet.` +
 `domainObjectAnnotation.` +
@@ -102,7 +102,7 @@ Configuration properties for the JDO/DataNucleus objectstore can be found in the
 `postForDefault`
 |`true`,`false` +
 (`true`)
-|Whether an event should be posted if xref:rgant.adoc#_rgant-DomainObject_removingLifecycleEvent[`@DomainObject#removingLifecycleEvent()`] is not specified (is set to `ObjectRemovingEvent.Default`).
+|Whether an event should be posted if xref:../rgant/rgant.adoc#_rgant-DomainObject_removingLifecycleEvent[`@DomainObject#removingLifecycleEvent()`] is not specified (is set to `ObjectRemovingEvent.Default`).
 
 |`isis.reflector.facet.` +
 `domainObjectAnnotation.` +
@@ -110,7 +110,7 @@ Configuration properties for the JDO/DataNucleus objectstore can be found in the
 `postForDefault`
 |`true`,`false` +
 (`true`)
-|Whether an event should be posted if xref:rgant.adoc#_rgant-DomainObject_updatingLifecycleEvent[`@DomainObject#updatingLifecycleEvent()`] is not specified (is set to `ObjectUpdatingEvent.Default`).
+|Whether an event should be posted if xref:../rgant/rgant.adoc#_rgant-DomainObject_updatingLifecycleEvent[`@DomainObject#updatingLifecycleEvent()`] is not specified (is set to `ObjectUpdatingEvent.Default`).
 
 |`isis.reflector.facet.` +
 `domainObjectAnnotation.` +
@@ -118,7 +118,7 @@ Configuration properties for the JDO/DataNucleus objectstore can be found in the
 `postForDefault`
 |`true`,`false` +
 (`true`)
-|Whether an event should be posted if xref:rgant.adoc#_rgant-DomainObject_updatedLifecycleEvent[`@DomainObject#updatedLifecycleEvent()`] is not specified (is set to `ObjectUpdatedEvent.Default`).
+|Whether an event should be posted if xref:../rgant/rgant.adoc#_rgant-DomainObject_updatedLifecycleEvent[`@DomainObject#updatedLifecycleEvent()`] is not specified (is set to `ObjectUpdatedEvent.Default`).
 
 
 
@@ -145,21 +145,21 @@ Configuration properties for the JDO/DataNucleus objectstore can be found in the
 `cssClassUiEvent.postForDefault`
 |`true`,`false` +
 (`true`)
-|Whether an event should be posted if xref:rgant.adoc#_rgant-DomainObjectLayout_cssClassUiEvent[`@DomainObjectLayout#cssClassUiEvent()`] is not specified (is set to `CssClassUiEvent.Default`).
+|Whether an event should be posted if xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_cssClassUiEvent[`@DomainObjectLayout#cssClassUiEvent()`] is not specified (is set to `CssClassUiEvent.Default`).
 
 |`isis.reflector.facet.` +
 `domainObjectLayoutAnnotation.` +
 `iconUiEvent.postForDefault`
 |`true`,`false` +
 (`true`)
-|Whether an event should be posted if xref:rgant.adoc#_rgant-DomainObjectLayout_iconUiEvent[`@DomainObjectLayout#iconUiEvent()`] is not specified (is set to `IconUiEvent.Default`).
+|Whether an event should be posted if xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_iconUiEvent[`@DomainObjectLayout#iconUiEvent()`] is not specified (is set to `IconUiEvent.Default`).
 
 |`isis.reflector.facet.` +
 `domainObjectLayoutAnnotation.` +
 `titleUiEvent.postForDefault`
 |`true`,`false` +
 (`true`)
-|Whether an event should be posted if xref:rgant.adoc#_rgant-DomainObjectLayout_titleUiEvent[`@DomainObjectLayout#titleUiEvent()`] is not specified (is set to `TitleUiEvent.Default`).
+|Whether an event should be posted if xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_titleUiEvent[`@DomainObjectLayout#titleUiEvent()`] is not specified (is set to `TitleUiEvent.Default`).
 
 
 
@@ -185,9 +185,9 @@ Configuration properties for the JDO/DataNucleus objectstore can be found in the
 |`FQCN`,`FQCN2`,...
 |Fully qualified class names of classes to be instantiated as domain services.  +
 
-Each entry can be optionally prefixed by "n:" specifying the relative order on the menu (corresponds to xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`]).
+Each entry can be optionally prefixed by "n:" specifying the relative order on the menu (corresponds to xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`]).
 
-This property is IGNORED if the xref:rgcfg.adoc#_rgcfg_configuring-components[`isis.appManifest`] configuration property is specified, or if an xref:rgcms.adoc#_rgcms_classes_super_AppManifest[`AppManifest`] is provided programmatically.
+This property is IGNORED if the xref:../rgcfg/rgcfg.adoc#_rgcfg_configuring-components[`isis.appManifest`] configuration property is specified, or if an xref:../rgcms/rgcms.adoc#_rgcms_classes_super_AppManifest[`AppManifest`] is provided programmatically.
 
 
 |`isis.services.` +
@@ -206,14 +206,14 @@ Lazy initialization can speed up bootstrapping, useful while developing and runn
 `objects`
 | `all`, `none` +
 (`all`)
-|Whether the changed properties of objects should be automatically audited (for objects annotated with xref:rgant.adoc#_rgant-DomainObject_auditing[`@DomainObject(auditing=Auditing.AS_CONFIGURED)`].
+|Whether the changed properties of objects should be automatically audited (for objects annotated with xref:../rgant/rgant.adoc#_rgant-DomainObject_auditing[`@DomainObject(auditing=Auditing.AS_CONFIGURED)`].
 
 
 |`isis.services.` +
 `command.` +
 `actions`
 | `all`, `ignoreSafe`, `none` (`all`)
-|Whether action invocations should be automatically reified into commands (for actions annotated with xref:rgant.adoc#_rgant-Action_command[`@Action(command=CommandReification.AS_CONFIGURED)`].  +
+|Whether action invocations should be automatically reified into commands (for actions annotated with xref:../rgant/rgant.adoc#_rgant-Action_command[`@Action(command=CommandReification.AS_CONFIGURED)`].  +
 
 `ignoreQueryOnly` is an alias for `ignoreSafe`.
 
@@ -221,7 +221,7 @@ Lazy initialization can speed up bootstrapping, useful while developing and runn
 `command.` +
 `properties`
 | `all`, `none` (`all`)
-|(Whether property edits should be automatically reified into commands (for properties annotated with xref:rgant.adoc#_rgant-Property_command[`@Property(command=CommandReification.AS_CONFIGURED)`].  +
+|(Whether property edits should be automatically reified into commands (for properties annotated with xref:../rgant/rgant.adoc#_rgant-Property_command[`@Property(command=CommandReification.AS_CONFIGURED)`].  +
 
 
 |`isis.services.` +
@@ -241,7 +241,7 @@ Lazy initialization can speed up bootstrapping, useful while developing and runn
 (depends)
 |If a domain object has been mapped to the specified JAXB `x-ro-domain-type`, then determines whether the result is pretty-printed or not. +
 
-If no configuration property is available, then the defaults is determined by the xref:rgcfg.adoc#_rgcfg_deployment-types[deployment type]: production mode disables pretty printing, while prototype mode enables it.
+If no configuration property is available, then the defaults is determined by the xref:../rgcfg/rgcfg.adoc#_rgcfg_deployment-types[deployment type]: production mode disables pretty printing, while prototype mode enables it.
 
 
 
@@ -277,7 +277,7 @@ NB: note that the key is mis-spelt, (`isis.service.email` rather than `isis.serv
 `email.` +
 `port` +
 | port number (`_587_`)
-|The port number for the SMTP service on the the external SMTP host (used by xref:rgsvc.adoc#_rgsvc_api_EmailService[`EmailService`]).  +
+|The port number for the SMTP service on the the external SMTP host (used by xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EmailService[`EmailService`]).  +
 
 NB: note that the key is mis-spelt, (`isis.service.email` rather than `isis.services.email`)
 
@@ -286,7 +286,7 @@ NB: note that the key is mis-spelt, (`isis.service.email` rather than `isis.serv
 `email.` +
 `sender.address` +
 | email address
-|The email address to use for sending out email (used by xref:rgsvc.adoc#_rgsvc_api_EmailService[`EmailService`]).
+|The email address to use for sending out email (used by xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EmailService[`EmailService`]).
 *Mandatory*.  +
 
 NB: note that the key is mis-spelt, (`isis.service.email` rather than `isis.services.email`)
@@ -296,7 +296,7 @@ NB: note that the key is mis-spelt, (`isis.service.email` rather than `isis.serv
 `email.` +
 `sender.hostname` +
 | host (`_smtp.gmail.com_`)
-|The hostname of the external SMTP provider (used by xref:rgsvc.adoc#_rgsvc_api_EmailService[`EmailService`]).  +
+|The hostname of the external SMTP provider (used by xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EmailService[`EmailService`]).  +
 
 NB: note that the key is mis-spelt, (`isis.service.email` rather than `isis.services.email`)
 
@@ -305,7 +305,7 @@ NB: note that the key is mis-spelt, (`isis.service.email` rather than `isis.serv
 `email.` +
 `sender.password` +
 | email password
-|The corresponding password for the email address to use for sending out email (used by xref:rgsvc.adoc#_rgsvc_api_EmailService[`EmailService`]).
+|The corresponding password for the email address to use for sending out email (used by xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EmailService[`EmailService`]).
 *Mandatory*.  +
 
 NB: note that the key is mis-spelt, (`isis.service.email` rather than `isis.services.email`)
@@ -350,7 +350,7 @@ NB: note that the key is mis-spelt, (`isis.service.email` rather than `isis.serv
 `tls.enabled`
 |`true`,`false` +
 (`true`)
-|Whether to enable TLS for the email SMTP connection (used by xref:rgsvc.adoc#_rgsvc_api_EmailService[`EmailService`]).  +
+|Whether to enable TLS for the email SMTP connection (used by xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EmailService[`EmailService`]).  +
 
 NB: note that the key is mis-spelt, (`isis.service.email` rather than `isis.services.email`)
 
@@ -360,7 +360,7 @@ NB: note that the key is mis-spelt, (`isis.service.email` rather than `isis.serv
 `implementation` +
 | `guava`, `axon`, +
 FQCN (`_guava_`)
-|which implementation to use by the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] as the underlying event bus.
+|which implementation to use by the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] as the underlying event bus.
 
 | `isis.services.` +
 `eventbus.` +
@@ -368,7 +368,7 @@ FQCN (`_guava_`)
 `Registration` +
 |`true`,`false` +
 (`false`)
-|whether a domain service can register with the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] after any events have posted. +
+|whether a domain service can register with the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] after any events have posted. +
 
 Since this almost certainly constitutes a bug in application code, by default this is disallowed.
 
@@ -426,20 +426,20 @@ If the setting is changed to disabled then this may reduce application start-up
 `objects`
 | `all`, `none` +
 (`all`)
-|Whether changed objects should be automatically published (for objects annotated with xref:rgant.adoc#_rgant-DomainObject_publishing[`@DomainObject(publishing=Publishing.AS_CONFIGURED)`].
+|Whether changed objects should be automatically published (for objects annotated with xref:../rgant/rgant.adoc#_rgant-DomainObject_publishing[`@DomainObject(publishing=Publishing.AS_CONFIGURED)`].
 
 
 |`isis.services.` +
 `publish.` +
 `actions`
 | `all`, `ignoreSafe`, `none` (`none`)
-|Whether actions should be automatically published (for actions annotated with xref:rgant.adoc#_rgant-Action_publishing[`@Action(publishing=Publishing.AS_CONFIGURED)`]. +
+|Whether actions should be automatically published (for actions annotated with xref:../rgant/rgant.adoc#_rgant-Action_publishing[`@Action(publishing=Publishing.AS_CONFIGURED)`]. +
 
 |`isis.services.` +
 `publish.` +
 `properties`
 | `all`, `none` (`none`)
-|Whether properties should be automatically published (for properties annotated with xref:rgant.adoc#_rgant-Action_publishing[`@Property(publishing=Publishing.AS_CONFIGURED)`]. +
+|Whether properties should be automatically published (for properties annotated with xref:../rgant/rgant.adoc#_rgant-Action_publishing[`@Property(publishing=Publishing.AS_CONFIGURED)`]. +
 
 
 |`isis.services.` +
@@ -449,7 +449,7 @@ If the setting is changed to disabled then this may reduce application start-up
 |fully qualified package names (CSV)
 |to search for domain services (including all subpackages).
 
-This property is IGNORED if the xref:rgcfg.adoc#_rgcfg_configuring-components[`isis.appManifest`] configuration property is specified, or if an xref:rgcms.adoc#_rgcms_classes_super_AppManifest[`AppManifest`] is provided programmatically.
+This property is IGNORED if the xref:../rgcfg/rgcfg.adoc#_rgcfg_configuring-components[`isis.appManifest`] configuration property is specified, or if an xref:../rgcms/rgcms.adoc#_rgcms_classes_super_AppManifest[`AppManifest`] is provided programmatically.
 
 
 |`isis.services.` +
@@ -507,7 +507,7 @@ See also `isis.reflector.facets.ignoreDeprecated`.
 (`false`)
 | Whether to check that the class has an object type explicitly specified somehow.
 
-The object type is used by the framework as an alias for the object's concrete class; it is one part of the object's OID and can be seen in the URLs of the xref:ugvw.adoc#[Wicket viewer] and xref:ugvro.adoc#[Restful Objects viewer], and is encoded in the ``Bookmark``s returned by the xref:rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`].
+The object type is used by the framework as an alias for the object's concrete class; it is one part of the object's OID and can be seen in the URLs of the xref:ugvw.adoc#[Wicket viewer] and xref:ugvro.adoc#[Restful Objects viewer], and is encoded in the ``Bookmark``s returned by the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`].
 In this was it may also be persisted, for example in polymorphic associations or command or auditing tables.
 
 If the object type is not specified explicitly, then this can cause data migration issues if the class is subsequently refactored (eg renamed, or moved to a different package).
@@ -544,10 +544,10 @@ This is by way of possibly deprecating and eventually moving contributed service
 `noParamsOnly`
 |`true`,`false` +
 (`false`)
-| When searching for  xref:rgcms.adoc#_rgcms_methods_prefixes_disable[`disableXxx()`] or xref:rgcms.adoc#_rgcms_methods_prefixes_hide[`hideXxx()`] methods, whether to search only for the no-param version (or also for supporting methods that match the parameter types of the action). +
+| When searching for  xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_disable[`disableXxx()`] or xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_hide[`hideXxx()`] methods, whether to search only for the no-param version (or also for supporting methods that match the parameter types of the action). +
 
 If enabled then will not search for supporting methods with the exact set of arguments as the method it was supporting (and any supporting methods that have additional parameters will be treated as invalid).
-Note that this in effect means that xref:rgcms.adoc#_rgcms_classes_mixins[mixins] must be used instead of xref:ugbtb.adoc#_ugbtb_decoupling_contributions[contributed services].
+Note that this in effect means that xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins[mixins] must be used instead of xref:ugbtb.adoc#_ugbtb_decoupling_contributions[contributed services].
 
 
 |`isis.reflector.validator.` +
@@ -579,7 +579,7 @@ If enabled, this configuration property will ensure that domain services only de
 `editing`
 |`true`,`false` +
 (`true`)
-|Whether objects' properties and collections can be edited directly (for objects annotated with xref:rgant.adoc#_rgant-DomainObject_editing[`@DomainObject#editing()`]); see xref:rgcfg.adoc#__rgcfg_configuring-core_isis-objects-editing[below] for further discussion.
+|Whether objects' properties and collections can be edited directly (for objects annotated with xref:../rgant/rgant.adoc#_rgant-DomainObject_editing[`@DomainObject#editing()`]); see xref:../rgcfg/rgcfg.adoc#__rgcfg_configuring-core_isis-objects-editing[below] for further discussion.
 
 
 |`isis.persistor.` +
@@ -597,14 +597,14 @@ Only intended for "emergency use" as a workaround while pending fix/patch to Apa
 |regex:css1, regex2:css2,...
 |Comma separated list of key:value pairs, where the key is a regex matching action names (eg `delete.*`) and the value is a link:http://getbootstrap.com/css/[Bootstrap] CSS button class (eg `btn-warning) to be applied (as per `@CssClass()`) to all action members matching the regex. +
 
-See xref:ugfun.adoc#_ugfun_how-tos_ui-hints_action-icons-and-css[UI hints] for more details.
+See xref:../ugfun/ugfun.adoc#_ugfun_how-tos_ui-hints_action-icons-and-css[UI hints] for more details.
 
 |`isis.reflector.facet.` +
 `cssClassFa.patterns`
 |regex:fa-icon,regex2:fa-icon2,...
 |Comma separated list of key:value pairs, where the key is a regex matching action names (eg `create.*`) and the value is a link:http://fortawesome.github.io/Font-Awesome/icons/[font-awesome] icon name (eg `fa-plus`) to be applied (as per `@CssClassFa()`) to all action members matching the regex. +
 
-See xref:ugfun.adoc#_ugfun_how-tos_ui-hints_action-icons-and-css[UI hints] for more details.
+See xref:../ugfun/ugfun.adoc#_ugfun_how-tos_ui-hints_action-icons-and-css[UI hints] for more details.
 
 
 |`isis.reflector.facet.` +
@@ -613,7 +613,7 @@ See xref:ugfun.adoc#_ugfun_how-tos_ui-hints_action-icons-and-css[UI hints] for m
 (`true`)
 |Whether objects should be filtered for visibility. +
 
-See xref:rgcfg.adoc#__rgcfg_configuring-core_filterVisibility[section below] for further discussion.
+See xref:../rgcfg/rgcfg.adoc#__rgcfg_configuring-core_filterVisibility[section below] for further discussion.
 
 |`isis.reflector.facets`
 |`FQCN`
@@ -679,7 +679,7 @@ See xref:ugbtb.adoc#_ugbtb_programming-model_layout-metadata-reader[Layout Metad
 `propertyLayout.labelPosition`
 |`TOP`, `LEFT` +
 (`LEFT`)
-|Default for label position for all properties if not explicitly specified using xref:rgant.adoc#_rgant-PropertyLayout_labelPosition[`@PropertyLayout#labelPosition()`]
+|Default for label position for all properties if not explicitly specified using xref:../rgant/rgant.adoc#_rgant-PropertyLayout_labelPosition[`@PropertyLayout#labelPosition()`]
 
 |===
 
@@ -717,7 +717,7 @@ By default this configuration property is enabled.  To disable the visibility fi
 isis.reflector.facet.filterVisibility=false
 ----
 
-Filtering is supported by the xref:ugvw.adoc#[Wicket viewer] and the xref:ugvro.adoc#[Restful Objects viewer], and also by the xref:rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`] domain service (provided the wrapper's execution mode is __not__ "skip rules").
+Filtering is supported by the xref:ugvw.adoc#[Wicket viewer] and the xref:ugvro.adoc#[Restful Objects viewer], and also by the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`] domain service (provided the wrapper's execution mode is __not__ "skip rules").
 
 [NOTE]
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgcfg/_rgcfg_deployment-types.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcfg/_rgcfg_deployment-types.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcfg/_rgcfg_deployment-types.adoc
index 0fe5e2d..b29d0f4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcfg/_rgcfg_deployment-types.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcfg/_rgcfg_deployment-types.adoc
@@ -9,7 +9,7 @@ Apache Isis distinguishes between the application being run in development mode
 
 (For mostly historical reasons) development mode is actually called `SERVER_PROTOTYPE`, while production mode is called just `SERVER`.  (There is also a deprecated mode called `SERVER_EXPLORATION`; for all intents and purposes this can considered as an alias of `SERVER_PROTOTYPE`).
 
-When running in development/prototyping mode, certain capabilities are enabled; most notably any actions restricted to prototyping mode (using xref:rgant.adoc#_rgant-Action_restrictTo[`@Action#restrictTo()`]) will be available.
+When running in development/prototyping mode, certain capabilities are enabled; most notably any actions restricted to prototyping mode (using xref:../rgant/rgant.adoc#_rgant-Action_restrictTo[`@Action#restrictTo()`]) will be available.
 
 
 

[22/58] [abbrv] isis git commit: ISIS-1521: working on ugfun.adoc

[da...@apache.org]

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_domain-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_domain-services.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_domain-services.adoc
deleted file mode 100644
index 25b27db..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_domain-services.adoc
+++ /dev/null
@@ -1,229 +0,0 @@
-[[_ugfun_domain-class-ontology_domain-services]]
-= Domain Services
-: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/
-
-
-In Apache Isis domain services have several responsibilities:
-
-- to expose actions to be rendered in the menu
-- to provide actions that are rendered as contributed actions/properties/collections on the contributee domain object
-- they act as subscribers to the event bus
-- they act as repositories (find existing objects) or as factories (create new objects)
-- they provide other services (eg performing calculations, attach a barcode, send an email etc).
-- to implement an SPI of the framework, most notably cross-cutting concerns such as security, command profiling, auditing and publishing.
-
-It's worth extending the xref:../ugfun/ugfun.adoc#_ugfun_core-concepts_philosophy_hexagonal-architecture[Hexagonal Architecture] to show where domain services fit in:
-
-.The hexagonal architecture with Isis addons
-image::{_imagesdir}core-concepts/philosophy/hexagonal-architecture-addons.png[width="700px"]
-
-The (non-ASF) link:http://isisaddons.org[Isis Addons] provide SPI implementations of the common cross-cutting concerns.
-They also provide a number of APIs for domain objects to invoke (not shown in the diagram).
-You can also write your own domain services as well, for example to interface with some external CMS system, say.
-
-
-
-[[__ugfun_domain-class-ontology_domain-services_organizing-services]]
-== Organizing Services
-
-In larger applications we have found it worthwhile to ensure that our domain services only act aligned with these responsibilities, employing a naming convention so that it is clear what the responsibilities of each domain service is.
-
-The application provides the `@DomainService(nature=...)` annotation that helps distinguish some of these responsibilities:
-
-- `VIEW` indicates that the actions should appear both on the menu and also be used as contributions
-- `VIEW_MENU_ONLY` indicates that the actions should appear on the menu
-- `VIEW_CONTRIBUTIONS_ONLY` indicates that the actions should not appear on the menu
-- `DOMAIN` indicates that the actions are for other domain objects to invoke (either directly or indirectly through the event bus), but in any case should not be rendered at all in the UI
-
-Pulling all the above together, here are our suggestions as to how you should organize your domain services.
-
-
-[[__ugfun_domain-class-ontology_domain-services_factory-and-repository]]
-== Factory and Repository
-
-The factory/repository uses an injected xref:../rgsvc/rgsvc.adoc#_rgsvc_api_RepositoryService[`RepositoryService`] to both instantiate new objects and to query the database for existing objects of a given entity type.  It is not visible in UI, rather other services delegate to it.
-
-We suggest naming such classes `XxxRepository`, eg:
-
-
-[source,java]
-----
-@DomainService(
-    nature=NatureOfService.DOMAIN                               // <1>
-)
-public CustomerRepository {
-    public List<Customer> findCustomerBy...(...) {
-        return repositoyService.allMatches(...);
-    }
-    public Customer newCustomer(...) {
-        Customer Customer = container.newTransientInstance(Customer.class);
-        ...
-        persistIfNotAlready(Customer);
-        return Customer;
-    }
-    public List<Customer> allCustomers() {
-        return repositoryService.allInstances(Customer.class);
-    }
-    @Inject
-    RepositoryService repositoryService;
-}
-----
-<1> interacted with only programmatically by other objects in the domain layer.
-
-There is no need to annotate the actions; they are implicitly hidden because of the domain service's nature.
-
-
-[[__ugfun_domain-class-ontology_domain-services_menu]]
-== Menu
-
-Menu services provide actions to be rendered on the menu.
-
-For the Wicket viewer, each service's actions appear as a collection of menu items of a named menu, and this menu is on one of the three menu bars provided by the Wicket viewer.  It is possible for more than one menu service's actions to appear on the same menu; a separator is shown between each.
-
-For the Restful Objects viewer, all menu services are shown in the services representation.
-
-We suggest naming such classes `XxxMenu`, eg:
-
-
-[source,java]
-----
-@DomainService(
-    nature = NatureOfService.VIEW_MENU_ONLY                     // <1>
-)
-@DomainServiceLayout(
-        named = "Customers",                                    // <2>
-        menuBar = DomainServiceLayout.MenuBar.PRIMARY,
-        menuOrder = "10"
-)
-public class CustomerMenu {
-    @Action(
-            semantics = SemanticsOf.SAFE
-    )
-    @MemberOrder( sequence = "1" )
-    public List<Customer> findCustomerBy...(...) {
-        return customerRepository.findCustomerBy(...);          // <3>
-    }
-
-    @Action(
-            semantics = SemanticsOf.NON_IDEMPOTENT
-    )
-    @MemberOrder( sequence = "3" )
-    public Customer newCustomer(...) {
-        return customerRepository.newCustomer(...);
-    }
-
-    @Action(
-            semantics = SemanticsOf.SAFE,
-            restrictTo = RestrictTo.PROTOTYPING
-    )
-    @MemberOrder( sequence = "99" )
-    public List<Customer> allCustomers() {
-        return customerRepository.allBankMandates();
-    }
-
-    @Inject
-    protected CustomerRepository customerRepository;
-}
-----
-<1> the service's actions should be rendered as menu items
-<2> specifies the menu name.  All services with the same menu name will be displayed on the same menu, with separators between
-<3> delegates to an injected repository.
-
-Not every action on the repository need to be delegated to of course (the above example does but only because it is very simple).
-
-[TIP]
-====
-Note also that while there's nothing to stop `VIEW_MENU` domain services being injected into other domain objects and interacted with programmatically, we recommend against it.  Instead, inject the underlying repository.  If there is additional business logic, then consider introducing a further `DOMAIN`-scoped service and call that instead.
-====
-
-
-
-[[__ugfun_domain-class-ontology_domain-services_contributions]]
-== Contributions (deprecated)
-
-
-Services can contribute either actions, properties or collections, based on the type of their parameters.
-
-[TIP]
-====
-Contributed services can instead be implemented as
-xref:../ugfun/ugfun.adoc#_ugfun_domain-class-ontology_mixins[mixins].
-As such, contributed services should be considered as deprecated.
-====
-
-We suggest naming such classes `XxxContributions`, eg:
-
-[source,java]
-----
-@DomainService(
-    nature=NatureOfService.VIEW_CONTRIBUTIONS_ONLY              // <1>
-)
-@DomainServiceLayout(
-    menuOrder="10",
-    name="...",
-}
-public class OrderContributions {
-    @Action(semantics=SemanticsOf.SAFE)
-    @ActionLayout(contributed=Contributed.AS_ASSOCIATION)       // <2>
-    @CollectionLayout(render=RenderType.EAGERLY)
-    public List<Order> orders(Customer customer) {              // <3>
-        return container.allMatches(...);
-    }
-
-    @Inject
-    CustomerRepository customerRepository;
-}
-----
-<1> the service's actions should be contributed to the entities of the parameters of those actions
-<2> contributed as an association, in particular as a collection because returns a `List<T>`.
-<3> Only actions with a single argument can be contributed as associations
-
-More information about contributions can be found xref:../ugfun/ugfun.adoc#_ugfun_how-tos_contributed-members[here].  More information
-about using contributions and mixins to keep your domain application decoupled can be found xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_contributions[here] and xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_mixins[here].
-
-
-
-
-[[__ugfun_domain-class-ontology_domain-services_event-subscribers]]
-== Event Subscribers
-
-Event subscribers can both veto interactions (hiding members, disabling members or validating changes), or can react to interactions (eg action invocation or property edit).
-
-We suggest naming such classes `XxxSubscriptions`, eg:
-
-[source,java]
-----
-@DomainService(
-    nature=NatureOfService.DOMAIN                       // <1>
-)
-@DomainServiceLayout(
-    menuOrder="10",
-    name="...",
-}
-public class CustomerOrderSubscriptions {
-    @com.google.common.eventbus.Subscribe
-    public void on(final Customer.DeletedEvent ev) {
-        Customer customer = ev.getSource();
-        orderRepository.delete(customer);
-    }
-    @Inject
-    OrderRepository orderRepository;
-}
-----
-<1> subscriptions do not appear in the UI at all, so should use the domain nature of service
-
-
-
-== Prototyping
-
-While for long-term maintainability we do recommend the naming conventions described xref:../ugfun/ugfun.adoc#__ugfun_domain-class-ontology_domain-services_organizing-services[above], you can get away with far fewer services when just prototyping a domain.
-
-If the domain service nature is not specified (or is left to its default, `VIEW`), then the service's actions will
-appear in the UI both as menu items _and_ as contributions (and the service can of course be injected into other domain objects for programmatic invocation).
-
-Later on it is easy enough to refactor the code to tease apart the different responsibilities.
-
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_mixins.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_mixins.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_mixins.adoc
deleted file mode 100644
index 0acc6cb..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_mixins.adoc
+++ /dev/null
@@ -1,56 +0,0 @@
-[[_ugfun_domain-class-ontology_mixins]]
-= Mixins
-: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/
-
-
-
-A mixin object allows one class to contribute behaviour - actions, (derived) properties and (derived) collections - to another domain object, either a domain entity or view model.
-
-Some programming languages use the term "trait" instead of mixin, and some languages (such as AspectJ) define their own syntax for defining such constructs.
-In Apache Isis a mixin is very similar to a domain service, however it also defines a single 1-arg constructor that defines the type of the domain objects that it contributes to.
-
-Why do this?
-Two reasons:
-
-* The main reason is to allow the app to be decoupled, so that it doesn't degrade into the proverbial link:http://www.laputan.org/mud/mud.html#BigBallOfMud["big ball of mud"].
-Mixins (and contributions) allow dependency to be inverted, so that the dependencies between modules can be kept acyclic and under control.
-
-* However, there is another reason: mixins are also a convenient mechanism for grouping functionality even for a concrete type, helping to rationalize about the dependency between the data and the behaviour.
-
-Both use cases are discussed below.
-
-Syntactically, a mixin is defined using either the xref:../rgant/rgant.adoc#_rgant_Mixin[`@Mixin`] annotation or using xref:../rgant/rgant.adoc#_rgant_DomainObject_nature[`@DomainObject#nature()`] attribute (specifying a nature of `Nature.MIXIN`).
-
-
-
-[source,java]
-----
-@Mixin(method="coll")                                       // <1>
-public class Customer_orders {                              // <2>
-
-    private final Customer customer;
-    public Customer_orders(final Customer customer) {       // <3>
-        this.customer = customer;
-    }
-
-    @Action(semantics=SemanticsOf.SAFE)                     // <4>
-    @ActionLayout(contributed=Contributed.AS_ASSOCIATION)   // <4>
-    @CollectionLayout(render=RenderType.EAGERLY)
-    public List<Order> coll() {                             // <1>
-        return repositoryService.findOrdersFor(customer);
-    }
-
-    @Inject
-    RepositoryService repositoryService;
-}
-----
-<1> indicates that this is a mixin, with "coll" as the name of the main method
-<2> The contributed member is inferred from the name, after the "_"; in other words "orders"
-<3> The mixee is `Customer`.
-This could also be an interface.
-<4> Indicates that the action should be interpreted as a collection.
-This requires that the action has safe semantics, ie does not alter state/no side-effects.
-
-There is further discussion of mixins in the xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_mixins[beyond the basics] guide.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_view-models.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_view-models.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_view-models.adoc
deleted file mode 100644
index 4e510ac..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_view-models.adoc
+++ /dev/null
@@ -1,196 +0,0 @@
-[[_ugfun_domain-class-ontology_view-models]]
-= View Models
-: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/
-
-
-
-View models are similar to entities in that (unlike domain services) there can be many instances of any given type; but they differ from entities in that they are not persisted into a database.
-Instead they are recreated dynamically by serializing their state, ultimately into the URL itself.
-
-When developing an Apache Isis application you will most likely start off with the persistent domain entities:
-`Customer`, `Order`, `Product`, and so on.
-
-For some applications this may well suffice.  However, if the application
-needs to integrate with other systems, or if the application needs to support reasonably complex business processes, then you may need to look beyond just domain entities, to view models.
-This section explores these use cases.
-
-
-
-
-[[__ugfun_domain-class-ontology_view-models_externally-managed-entities]]
-== Externally-managed entities
-
-Sometimes the entities that make up your application are persisted not in the local JDO/DataNucleus database
-but reside in some other system, for example accessible only through a SOAP web service.  Logically that data
-might still be considered a domain entity and we might want to associate behaviour with it, however it cannot be
-modelled as a domain entity if only because JDO/DataNucleus doesn't know about the entity nor how to retrieve or
-update it.
-
-There are a couple of ways around this: we could either replicate the data somehow from the external system into the
- Isis-managed database (in which case it is once again just another domain entity), or we could set up a stub/proxy for
- the externally managed entity.  This proxy would hold the reference to the externally-managed domain entity (eg an
- external id), as well as the "smarts" to know how to interact with that entity (by making SOAP web service calls etc).
-
-The stub/proxy is a type of view model: a view - if you like - onto the domain entity managed by the external system.
-
-[NOTE]
-====
-DataNucleus does in fact define its own link:http://www.datanucleus.org/documentation/extensions/store_manager.html[Store Manager] extension point, so an alternative architecture would be to implement this interface such that DataNucleus
-could make the calls to the external system; these externally-persisted domain entities would therefore be modelled as regular `@PersistenceCapable` entities after all.  For entities not persisted externally the implementation would delegate down to the default RDBMS-specific `StoreManager` provided by DataNucleus itself.
-
-An implementation that supported only reading from an external entity ought to be comparatively straight-forward, but
-implementing one that also supported updating external entities would need to carefully consider error conditions if the
-external system is unavailable; distributed transactions are most likely difficult/impossible to implement (and not
-desirable in any case).
-====
-
-
-[[__ugfun_domain-class-ontology_view-models_in-memory-entities]]
-== In-memory entities
-
-As a variation on the above, sometimes there are domain objects that are, conceptually at least entities, but whose
-state is not actually persisted anywhere, merely held in-memory (eg in a hash).
-
-A simple example might be read-only configuration data that is read from a config file (eg log4j appender
-definitions) but thereafter is presented in the UI just like any other entity.
-
-
-[[__ugfun_domain-class-ontology_view-models_application-layer-view-models]]
-== Application-layer view models
-
-Domain entities (whether locally persisted using JDO/DataNucleus or managed externally) are the bread-and-butter of Apache Isis applications: the focus after all, should be on the business domain concepts and ensuring that they are
-solid.  Generally those domain entities will make sense to the business domain experts: they form the _ubiquitous language_ of the domain.  These domain entities are part of the domain layer.
-
-That said, it may not always be practical to expect end-users of the application to interact solely with those domain
-entities.  For example, it may be useful to show a dashboard of the most significant data in the system to a user,
-often pulling in and aggregating information from multiple points of the app.  Obtaining this information by hand (by
- querying the respective services/repositories) would be tedious and slow; far better to have a dashboard do the job for
- the end user.
-
-A dashboard object is a model of the most relevant state to the end-user, in other words it is (quite literally) a view
- model.  It is not a persisted entity, instead it belongs to the application layer.
-
-A view model need not merely aggregate data; it could also provide actions of its own.  Most likely these actions will
-be queries and will always ultimately just delegate down to the appropriate domain-layer service/repository.  But in
-some cases such view model actions might also modify state of underlying domain entities.
-
-Another common use for view models is to help co-ordinate complex business processes; for example to perform a
-quarterly invoicing run, or to upload annual interest rates from an Excel spreadsheet.  In these cases the view model
-might have some state of its own, but in most cases that state does not need to be persisted per se.
-
-.Desire Lines
-****
-One way to think of application view models is as modelling the "desire line": the commonly-trod path
-that end-users must follow to get from point A to point B as quickly as possible.
-
-To explain: there are link:http://ask.metafilter.com/62599/Where-the-sidewalk-ends[documented]
-link:https://sivers.org/walkways[examples]
-link:http://www.softpanorama.org/People/Wall/larry_wall_articles_and_interviews.shtml[that] architects of university
-campus will only add in paths some while after the campus buildings are complete: let the pedestrians figure out the
-routes they want to take.  The name we like best for this idea is "desire lines", though it has also been called
-a "desire path", "paving the path" or "paving the sidewalk".
-
-What that means is you should add view models _after_ having built up the domain layer, rather than before.  These view
-models pave that commonly-trod path, automating the steps that the end-user would otherwise have to do by hand.
-
-It takes a little practice though, because even when building the domain layer "first", you should still bear in mind
-what the use cases are that those domain entities are trying to support.  You certainly _shouldn't_ try to build out a
-domain layer that could support every conceivable use case before starting to think about view models.
-
-Instead, you should iterate.  Identify the use case/story/end-user objective that you will deliver value to the
-business.  Then build out the minimum domain entities to support that use case (refining the xref:../ugfun/ugfun.adoc#__ugfun_core-concepts_philosophy_domain-driven-design_ubiquitous-language[ubiquitous language] as you
-go).  Then, identify if there any view models that could be introduced which would simplify the end-user interactions
-with the system (perhaps automating several related use cases together).
-****
-
-[[__ugfun_domain-class-ontology_view-models_dtos]]
-== DTOs
-
-DTOs (data transfer objects) are simple classes that (according to link:https://en.wikipedia.org/wiki/Data_transfer_object[wikipedia]) "carry data between processes".
-
-If those two processes are parts of the same overall application (the same team builds and deploys both server and
-client) then there's generally no need to define a DTO; just access the entities using Apache Isis'
-xref:../ugvro/ugvro.adoc#[RestfulObjects viewer].
-
-On the other hand, if the client consuming the DTO is a different application -- by which we mean developed/deployed by
-a different (possible third-party) team -- then the DTOs act as a formal contract between the provider and the consumer.
-In such cases, exposing domain entities over xref:../ugvro/ugvro.adoc#[RestfulObjects] would be
-"A Bad Thing"(TM) because the consumer would in effect have access to implementation details that could then not be
-easily changed by the producer.
-
-To support this use case, a view model can be defined such that it can act as a DTO.  This is done by annotating the
-class using JAXB annotations; this allows the consumer to obtain the DTO in XML format along with a corresponding
-XSD schema describing the structure of that XML.  A discussion of how that might be done using an ESB such as
-link:http://camel.apache.org[Apache Camel(TM)] follows xref:../ugbtb/ugbtb.adoc#__ugfun_domain-class-ontology_view-models_dtos_consumers[below].
-
-In case it's not obvious, these DTOs are still usable as "regular" view models; they will render in the xref:../ugvw/ugvw.adoc#[Wicket viewer] just like any other.  In fact (as the xref:../ugbtb/ugbtb.adoc#_ugbtb_view-models_programming-model[programming model] section below makes clear), these JAXB-annotated view models are in many regards the most powerful of all the alternative ways of writing view models.
-
-
-It's also worth noting that it is also possible to download the XML (or XSD) straight from the UI, useful during development.
-The view model simply needs to implement the xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins_Dto[`Dto`] marker interface; the
-framework has xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins_Dto[mixins] that contribute the download actions to the view model.
-
-
-[[__ugfun_domain-class-ontology_view-models_dtos_consumers]]
-=== DTO Consumers
-
-The actual consumers of DTOs will generally obtain the XML of the view models either by requesting the XML directly,
-eg using the xref:../ugvro/ugvro.adoc#[RestfulObjects viewer], or may have the XML sent to them asynchronously using an ESB
-such as Apache Camel.
-
-In the former case, the consumer requests the DTO by calling the REST API with the appropriate HTTP `Accept` header.
-An appropriate implementation of xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`] can then be
-used to return the appropriate DTO (as XML).
-
-For the latter case, one design is simply for the application to instantiate the view model, then call the
-xref:../rgsvc/rgsvc.adoc#_rgsvc_api_JaxbService[`JaxbService`] to obtain its corresponding XML.  This can then be published onto
-the ESB, for example using an http://activemq.apache.org[Apache ActiveMQ (TM)] queue.
-
-However, rather than try to push all the data that might be needed by any of these external systems in a single XML event
- (which would require anticipating all the requirements, likely a hopeless task), a better design is to publish only
- the fact that something of note has changed - ie, that an action on a domain object has been invoked - and then let the consumers call back to obtain other information if required.  This can once again be done by calling the REST API with
- an appropriate HTTP `Accept` header.
-
-[TIP]
-====
-This is an example of the link:https://leanpub.com/camel-design-patterns[VETRO pattern] (validate, enrich, transform, route, operate).  In our case we focus on the validation (to determine the nature of the inbound message, ie which action was
-invoked), and the enrich (callback to obtain a DTO with additional information required by the consumer).
-====
-
-The (non-ASF) http://github.com/isisaddons/isis-module-publishmq[Isis addons' publishmq] module provides an out-of-the-box solution of this design.  It provides an implementation of the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`],
-but which simply publishes instances of xref:../rgcms/rgcms.adoc#_rgcms_schema-aim[`ActionInvocationMemento`] to an ActiveMQ
-queue.  Camel (or similar) can then be hooked up to consume these events from this queue, and use a processor to
-parse the action memento to determine what has changed on the source system.  Thereafter, a subsequent Camel processor
-can then call back to the source - via the xref:../ugvro/ugvro.adoc[Restful Objects viewer] - to enrich the message with
-additional details using a DTO.
-
-
-
-
-
-[[__ugfun_domain-class-ontology_view-models_typical-implementation]]
-== Typical Implementation
-
-Apache Isis offers several ways to implement view models, but the most flexible/powerful is to annotate the class using JAXB annotations.
-For example:
-
-[source,java]
-----
-@XmlRootElement(name = "invoiceRun")    // <1>
-@XmlType(
-        propOrder = {                   // <2>
-            ...
-        }
-)
-public class InvoiceRun {
-    ...
-}
-----
-<1> The JAXB `@XmlRootElement` annotation indicates this is a view model to Apache Isis, which then uses JAXB to serialize the state of the view model between interactions
-<2> All properties of the view model must be listed using the `XmlType#propOrder` attribute.
-
-Use JAXB elements such as `@XmlElement` for properties and the combination of `@XmlElementWrapper` and `@XmlElement` for collections.
-Properties can be ignored (for serialization) using `@XmlTransient`.
-

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model.adoc
new file mode 100644
index 0000000..98fcff1
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model.adoc
@@ -0,0 +1,91 @@
+[[_ugfun_programming-model]]
+= Programming Model
+: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 works by building a metamodel of the domain objects: entities, domain services, view models and mixins.
+Dependent on the sort of domain object, the class methods represent
+both state -- (single-valued) properties and (multi-valued) collections -- and behaviour -- actions.
+
+More specifically, both entities and view models can have properties, collections and actions, while domain services have just actions.
+Mixins also define only actions, though depending on their semantics they may be rendered as derived properties or collections on the domain object to which they contribute.
+
+In the automatically generated UI a property is rendered as a field.
+This can be either of a value type (a string, number, date, boolean etc) or can be a reference to another entity.
+A collection is generally rendered as a table.
+
+In order for Apache Isis to build its metamodel the domain objects must follow some conventions: what we call the _Apache Isis Programming Model_.
+This is just an extension of the pojo / JavaBean standard of yesteryear: properties and collections are getters/setters, while actions are simply any remaining `public` methods.
+
+Additional metamodel semantics are inferred both imperatively from _supporting methods_ and declaratively from annotations.
+
+In this section we discuss the mechanics of writing domain objects that comply with Apache Isis' programming model.
+
+[TIP]
+====
+In fact, the Apache Isis programming model is extensible; you can teach Apache Isis new programming conventions and you can remove existing ones; ultimately they amount to syntax.
+The only real fundamental that can't be changed is the notion that objects consist of properties, collections and actions.
+
+You can learn more about extending Apache Isis programming model xref:../ugbtb/ugbtb.adoc#_ugbtb_programming-model[here].
+====
+
+
+The Apache Isis programming model uses annotations to distinguish these object types:
+
+* *view models* are annotated either with `@DomainObject(nature=VIEW_MODEL)` or using `@ViewModel` (which is used is a matter of personal preference); the framework will automatically manage the view model's state (properties only, not collections). +
++
+Or, they can be annotated using the JAXB `@XmlTypeAdapter` annotation, which allows the view models' properties _and_ collections state to be managed.
+
+* *domain entities* that are persisted to the database (as the vast majority will) are annotated with `@DomainObject(nature=ENTITY)`.
+In addition such domain entities are annotated with the JDO/DataNucleus annotation of
+`@javax.jdo.annotations.PersistenceCapable`. +
++
+In addition, if a domain entity is a proxy for state managed in an external system, or merely for some state held in-memory, then `@DomainObject(nature=EXTERNAL_ENTITY)` or `@DomainObject(nature=INMEMORY_ENTITY)` can be used. +
++
+These entities' state is managed by the framework, in the same ways as view models.
+Indeed, they can additionally be annotated using `@XmlTypeAdapter` if required.
+
+* *mixins* are annotated either with `@DomainObject(nature=MIXIN)` or using `@Mixin`.
+As for view models, which is used is a matter of personal preference.
+
+* finally, *domain services*` are annotated with `@DomainService(nature=...)` where the nature is either `VIEW_MENU_ONLY` (for domain services whose actions appear on the top-level menu bars), or `VIEW_CONTRIBUTIONS_ONLY` (for domain services whose actions are contributed to entities or view models), or `DOMAIN` (for domain services whose
+functionality is simply for other domain objects to invoke programmatically).
++
+It is also possible to specify a nature of simply `VIEW`, this combining `VIEW_MENU_ONLY` and `VIEW_CONTRIBUTIONS_ONLY`.
+This is in fact the default, useful for initial prototyping.
+A final nature is `VIEW_REST_ONLY` which is for domain services whose functionality is surfaced only by the xref:../ugvro/ugvro.adoc#[RestfulObjects viewer].
+
+You can generally recognize an Apache Isis domain class because it will be probably be annotated using `@DomainObject` and `@DomainService`.
+
+It's worth emphasising is that domain entities and view models hold state, whereas domain services are generally stateless.
+If a domain service does hold state (eg the `Scratchpad` service noted above) then it should be `@RequestScoped` so that this state is short-lived and usable only within a single request.
+
+The framework also defines supplementary annotations, `@DomainObjectLayout` and `@DomainServiceLayout`.
+These provide hints relating to the layout of the domain object in the user interface.
+(Alternatively, these UI hints can be defined in a supplementary xref:../ugvw/ugvw.adoc#_ugvw_layout[`.layout.xml`] file.
+
+
+
+
+include::_ugfun_programming-model_domain-entities.adoc[leveloffset=+1]
+
+include::_ugfun_programming-model_domain-services.adoc[leveloffset=+1]
+
+include::_ugfun_programming-model_view-models.adoc[leveloffset=+1]
+
+include::_ugfun_programming-model_mixins.adoc[leveloffset=+1]
+
+include::_ugfun_programming-model_properties.adoc[leveloffset=+1]
+include::_ugfun_programming-model_collections.adoc[leveloffset=+1]
+include::_ugfun_programming-model_actions.adoc[leveloffset=+1]
+
+include::_ugfun_programming-model_inject-services.adoc[leveloffset=+1]
+
+include::_ugfun_programming-model_properties-vs-parameters.adoc[leveloffset=+1]
+
+
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_actions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_actions.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_actions.adoc
new file mode 100644
index 0000000..80f657a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_actions.adoc
@@ -0,0 +1,264 @@
+[[_ugfun_programming-model_actions]]
+= Actions
+: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/
+
+
+
+While xref:../ugfun/ugfun.adoc#_ugfun_programming-model_properties[properties] and xref:../ugfun/ugfun.adoc#_ugfun_programming-model_collections[collections] define the state held by a domain object (its "know what" responsibilities), actions define the object's behaviour (its "know how-to" responsibilities).
+
+An application whose domain objects have only/mostly "know-what" responsibilities is pretty dumb: it requires that the end-user know the business rules and doesn't modify the state of the domain objects such that they are invalid (for example, an "end date" being before a "start date").
+Such applications are often called CRUD applications (create/read/update/delete).
+
+In more complex domains, it's not realistic/feasible to expect the end-user to have to remember all the different business rules that govern the valid states for each domain object.
+So instead actions allow those business rules to be encoded programmatically.
+An Apache Isis application doesn't try to constrain the end-user as to way in which they interact with the user (it doesn't attempt to define a rigid business process) but it does aim to ensure that business rule invariants are maintained, that is that business objects aren't allowed to go into an invalid state.
+
+For simple domain applications, you may want to start prototyping only with properties, and only later introduce actions (representing the most common business operations).
+But an alternative approach, recommended for more complex applications, is actually to start the application with all properties non-editable.
+Then, as the end-user requires the ability to modify some state, there is a context in which to ask the question "why does this state need to change?" and "are their any side-effects?" (ie, other state that changes at the same time, or other behaviour that should occur).
+If the state change is simple, for example just being able to correct an invalid address, or adding a note or comment, then that can probably be modelled as a simple editable property.
+But if the state change is more complex, then most likely an action should be used instead.
+
+
+[[__ugfun_programming-model_actions_defining-actions]]
+== Defining actions
+
+Broadly speaking, actions are all the `public` methods that are not getters or setters which represent properties or collections.
+This is a slight simplification; there are a number of other method prefixes (such as `hide` or `validate`) that represent xref:../ugfun/ugfun.adoc#_ugfun_business-rules[business rules]); these also not treated as actions.
+And, any method that are annotated with `@Programmatic` will also be excluded.
+But by and large, all other methods such as `placeOrder(...)` or `approveInvoice(...)` will be treated as actions.
+
+For example:
+
+[source,java]
+----
+@Action(semantics=SemanticsOf.IDEMPOTENT)       // <1>
+public ShoppingBasket addToBasket(
+        Product product,
+        @ParameterLayout(named="Quantity")      // <2>
+        int quantity
+        ) {
+    ...
+    return this;
+}
+----
+<1> `@Action` annotation is optional but used to specify additional domain semantics (such as being idempotent).
+<2> The names of action parameters (as rendered in the UI) will by default be the parameter types, not the paramter names.
+For the `product` parameter this is reasonable, but not so for the `quantity` parameter (which would by default show up with a name of "int".
+The `@ParameterLayout` annotation provides a UI hint to the framework.
+
+[TIP]
+====
+The (non-ASF) Isis addons' http://github.com/isisaddons/isis-metamodel-paraname8[paraname8] metamodel extension allows the parameter name to be used in the UI, rather than the type.
+====
+
+
+[[__ugfun_programming-model_actions_reference-parameter-types]]
+== (Reference) Parameter types
+
+Parameter types can be value types or reference types.
+In the case of primitive types, the end-user can just enter the value directly through the parameter field.
+In the case of reference types however (such as `Product`), a drop-down must be provided from which the end-user to select.
+This is done using either a supporting xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_choices[`choices`] or xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete`] method.
+The "choices" is used when there is a limited set of options, while "autoComplete" is used when there are large set of options such that the end-user must provide some characters to use for a search.
+
+For example, the `addToBasket(...)` action shown above might well have a :
+
+[source,java]
+----
+@Action(semantics=SemanticsOf.IDEMPOTENT)
+public ShoppingBasket addToBasket(
+        Product product,
+        @ParameterLayout(named="Quantity")
+        int quantity
+        ) {
+    ...
+    return this;
+}
+public List<Product> autoComplete0AddToBasket(              // <1>
+    @MinLength(3)                                           // <2>
+    String searchTerm) {
+    return productRepository.find(searchTerm);              // <3>
+}
+@javax.inject.Inject
+ProductRepository productRepository;
+----
+<1> Supporting `autoComplete` method.
+The "0" in the name means that this corresponds to parameter 0 of the "addToBasket" action (ie `Product`).
+It is also required to return a Collection of that type.
+<2> The xref:../rgant/rgant.adoc#_rgant_MinLength[`@MinLength`] annotation defines how many characters the end-user must enter before performing a search.
+<3> The implementation delegates to an injected repository service.  This is typical.
+
+Note that it is also valid to define "choices" and "autoComplete" for value types (such as `quantity`, above); it just isn't as common to do so.
+
+[[__ugfun_programming-model_actions_reference-parameter-types_removing-boilerplate]]
+=== Removing boilerplate
+
+To save having to define an `autoCompleteNXxx(...)` method everywhere that a reference to a particular type (such as `Product`) appears as an action parameter, it is also possible to use the `@DomainObject` annotation on `Product` itself:
+
+[source,java]
+----
+@DomainObject(
+    autoCompleteRepository=ProductRepository.class          // <1>
+    autoCompleteAction="find"                               // <2>
+)
+public class Product ... {
+    ...
+}
+----
+<1> Whenever an action parameter requiring a `Product` is defined, provide an autoComplete drop-down automatically
+<2> Use the "find" method of `ProductRepository` (rather than the default name of "autoComplete")
+
+(As noted above), if the number of available instances of the reference type is a small number (in other words, all of which could comfortably be shown in a drop-down) then instead the `choicesNXxx()` supporting method can be used.
+This too can be avoided by annotating the referenced class.
+
+For example, suppose we have an action to specify the `PaymentMethodType`, where there are only 10 or so such (Visa, Mastercard, Amex, Paypal etc).
+We could define this as:
+
+[source,java]
+----
+public Order payUsing(PaymentMethodType type) {
+    ...
+}
+----
+
+where `PaymentMethodType` would be annotated using:
+
+[source,java]
+----
+@DomainObject(
+    bounded=true                            // <1>
+)
+public class PaymentMethodType ... {
+    ...
+}
+----
+<1> only a small (ie "bounded") number of instances available, meaning that the framework should render all in a drop-down.
+
+
+[[__ugfun_programming-model_actions_collection-parameter-types]]
+== Collection Parameter types
+
+Action parameters can also be collections of values (for example `List<String>`), or can be collections of references (such as `List<Customer>`).
+
+For example:
+
+[source,java]
+----
+@Action(semantics=SemanticsOf.IDEMPOTENT)
+public ShoppingBasket addToBasket(
+        List<Product> products,
+        @ParameterLayout(named="Quantity") int quantity
+        ) {
+    ...
+    return this;
+}
+public List<Product> autoComplete0AddToBasket(@MinLength(3) String searchTerm) {
+    return ...
+}
+----
+
+As the example suggests, any collection parameter type must provide a way to select items, either by way of a "choices" or "autoComplete" supporting method or alternatively defined globally using xref:../rgant/rgant.adoc#_rgant_DomainObject[`@DomainObject`] on the referenced type (described xref:../ugfun/ugfun.adoc#__ugfun_programming-model_actions_reference-parameter-types_removing-boilerplate[above]).
+
+
+[[__ugfun_programming-model_actions_optional-parameters]]
+== Optional Parameters
+
+Whereas the xref:../ugfun/ugfun.adoc#__ugfun_programming-model_properties_optional-properties[optionality of properties] is defined using xref:../rgant/rgant.adoc#_rgant_Column_allowsNull[`@javax.jdo.annotations.Column#allowsNull()`], that JDO annotation cannot be applied to parameter types.
+Instead, either the xref:../rgant/rgant.adoc#_rgant_Nullable[`@Nullable`] annotation or the xref:../rgant/rgant.adoc#_rgant_Parameter_optionality[`@Parameter#optionality()`]  annotation/attribute is used.
+
+For example:
+
+[source,java]
+----
+@javax.jdo.annotations.Column(allowsNull="true")                // <1>
+@lombok.Getter @lombok.Setter
+private LocalDate shipBy;
+
+public Order invoice(
+                PaymentMethodType paymentMethodType,
+                @Nullable                                       // <2>
+                @ParameterLayout(named="Ship no later than")
+                LocalDate shipBy) {
+    ...
+    setShipBy(shipBy)
+    return this;
+}
+----
+<1> Specifies the property is optional.
+<2> Specifies the corresponding parameter is optional.
+
+See also xref:../ugfun/ugfun.adoc#_ugfun_programming-model_properties-vs-parameters[properties vs parameters].
+
+[[__ugfun_programming-model_actions_string-parameters]]
+== ``String`` Parameters (Length)
+
+Whereas the xref:../ugfun/ugfun.adoc#__ugfun_programming-model_properties_datatypes_strings[length of string properties] is defined using xref:../rgant/rgant.adoc#_rgant_Column_length[`@javax.jdo.annotations.Column#length()`], that JDO annotation cannot be applied to parameter types.
+Instead, the xref:../rgant/rgant.adoc#_rgant_Parameter_maxLength[`@Parameter#maxLength()`] annotation/attribute is used.
+
+For example:
+
+[source,java]
+----
+@javax.jdo.annotations.Column(length=50)                // <1>
+@lombok.Getter @lombok.Setter
+private String firstName;
+
+@javax.jdo.annotations.Column(length=50)
+@lombok.Getter @lombok.Setter
+private String lastName;
+
+public Customer updateName(
+                @Parameter(maxLength=50)                // <2>
+                @ParameterLayout(named="First name")
+                String firstName,
+                @Parameter(maxLength=50)
+                @ParameterLayout(named="Last name")
+                String lastName) {
+    setFirstName(firstName);
+    setLastName(lastName);
+    return this;
+}
+----
+<1> Specifies the property length using the JDO xref:../rgant/rgant.adoc#_rgant_Column_length[`@Column#length()`] annotation
+<2> Specifies the parameter length using the (Apache Isis) xref:../rgant/rgant.adoc#_rgant_Parameter_maxLength[`@Parameter#maxLength()`] annotation
+
+[IMPORTANT]
+====
+Incidentally, note in the above example that the new value is assigned to the properties using the setter methods; the action does not simply set the instance field directly.
+This is important, because it allows JDO/DataNucleus to keep track that this instance variable is "dirty" and so needs flushing to the database table before the transaction completes.
+====
+
+See also xref:../ugfun/ugfun.adoc#_ugfun_programming-model_properties-vs-parameters[properties vs parameters].
+
+[[__ugfun_programming-model_actions_bigdecimal-parameters]]
+== ``BigDecimal``s (Precision)
+
+Whereas the xref:../ugfun/ugfun.adoc#__ugfun_programming-model_properties_datatypes_bigdecimals[precision of BigDecimal properties] is defined using xref:../rgant/rgant.adoc#_rgant_Column_scale[`@javax.jdo.annotations.Column#scale()`], that JDO annotation cannot be applied to parameter types.
+Instead, the xref:../rgant/rgant.adoc#_rgant_Digits_fraction[`@javax.validation.constraints.Digits#fraction()`] annotation/attribute is used.
+
+For example:
+
+[source,java]
+----
+@javax.jdo.annotations.Column(scale=2)                              // <1>
+@lombok.Getter @lombok.Setter
+private BigDecimal discountRate;
+
+public Order updateDiscount(
+                @javax.validation.constraints.Digits(fraction=2)    // <2>
+                @ParameterLayout(named="Discount rate")
+                String discountRate) {
+    setDiscountRate(discountRate);
+    return this;
+}
+----
+<1> Specifies the property precision using xref:../rgant/rgant.adoc#_rgant_Column_scale[`@Column#scale()`]
+<2> Specifies the corresponding parameter precision using xref:../rgant/rgant.adoc#_rgant_Digits_fraction[`@Digits#fraction()`].
+
+See also xref:../ugfun/ugfun.adoc#_ugfun_programming-model_properties-vs-parameters[properties vs parameters].
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_collections.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_collections.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_collections.adoc
new file mode 100644
index 0000000..8a7aafe
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_collections.adoc
@@ -0,0 +1,121 @@
+[[_ugfun_programming-model_collections]]
+= Collections
+: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/
+
+
+A collection is an instance variable of a domain object, of a collection type that holds references to other domain objects.
+For example, a `Customer` may have a collection of ``Order``s).
+
+It's ok for a xref:../ugfun/ugfun.adoc#__ugfun_programming-model_class-definition_entities[domain entity] to reference another domain entity, and for a xref:../ugfun/ugfun.adoc#__ugfun_programming-model_class-definition_view-models[view model] to reference both view model and domain entities.
+However, it isn't valid for a domain entity to hold a persisted reference to view model (DataNucleus will not know how to persist that view model).
+
+Formally speaking, a collection is simply a regular JavaBean getter, returning a collection type (subtype of `java.util.Collection`).
+Most collections (those that are modifiable) will also have a setter and (if persisted) a backing instance field.
+And collections properties will also have a number of annotations:
+
+* Apache Isis defines its own set own `@Collection` annotation for capturing domain semantics.
+It also provides a `@CollectionLayout` for UI hints (though the information in this annotation may instead be provided by a supplementary xref:../ugvw/ugvw.adoc#_ugvw_layout[`.layout.xml`] file
+
+* the collections of domain entities are often annotated with various JDO/DataNucleus annotations, most notable `javax.jdo.annotations.Persistent`.
+This and other annotations can be used to specify if the association is bidirectional, and whether to define a link table or not to hold foreign key columns.
+
+* for the collections of view models, then JAXB annotations such as `@javax.xml.bind.annotation.XmlElementWrapper` and `@javax.xml.bind.annotation.XmlElement` will be present
+
+Apache Isis recognises some of these annotations for JDO/DataNucleus and JAXB and infers some domain semantics from them (for example, the maximum allowable length of a string property).
+
+Unlike xref:../ugfun/ugfun.adoc#_ugfun_programming-model_properties[properties], the framework (at least, the xref:../ugvw/ugvw.adoc[Wicket viewer]) does not allow collections to be "edited".
+Instead, xref:../ugfun/ugfun.adoc#_ugfun_programming-model_actions[action]s can be written that will modify the contents of the collection as a side-effect.
+For example, a `placeOrder(...)` action will likely add an `Order` to the `Customer#orders` collection.
+
+Since writing getter and setter methods adds quite a bit of boilerplate, it's common to use link:https://projectlombok.org/[Project Lombok] to code generate these methods at compile time (using Java's annotation processor) simply by adding the `@lombok.Getter` and `@lombok.Setter` annotations to the field.
+
+
+
+[[__ugfun_programming-model_collections_mapping-bidir-1m]]
+== Mapping bidir 1:m
+
+Bidirectional one-to-many collections are one of the most common types of associations between two entities.
+In the parent object, the collection can be defined as:
+
+[source,java]
+----
+public class ParentObject
+        implements Comparable<ParentObject>{
+
+    @javax.jdo.annotations.Persistent(
+        mappedBy = "parent",                                                // <1>
+        dependentElement = "false"                                          // <2>
+    )
+    @Collection                                                             // <3>
+    @lombok.Getter @lombok.Setter
+    private SortedSet<ChildObject> children = new TreeSet<ChildObject>();   // <4>
+
+}
+----
+<1> indicates a bidirectional association; the foreign key pointing back to the `Parent` will be in the table for `ChildObject`
+<2> disable cascade delete
+<3> (not actually required in this case, because no attributes are set, but acts as a useful reminder that this collection will be rendered in the UI by Apache Isis)
+<4> uses a `SortedSet` (as opposed to some other collection type; discussion below)
+
+while in the child object you will have:
+
+[source,java]
+----
+public class ChildObject
+        implements Comparable<ChildObject> {    // <1>
+
+    @javax.jdo.annotations.Column(
+        allowsNull = "false"                    // <2>
+    )
+    @Property(editing = Editing.DISABLED)       // <3>
+    @lombok.Getter @lombok.Setter
+    private ParentObject parent;
+}
+----
+<1> implements `Comparable` because is mapped using a `SortedSet`
+<2> mandatory; every child must reference its parent
+<3> cannot be edited directly
+
+Generally speaking you should use `SortedSet` for collection types (as opposed to `Set`, `List` or `Collection`).
+JDO/Datanucleus does support the mapping of these other types, but RDBMS are set-oriented, so using this type introduces the least friction.
+
+[NOTE]
+====
+For further details on mapping associations, see the JDO/DataNucleus documentation for link:http://www.datanucleus.org/products/accessplatform_4_1/jdo/orm/one_to_many.html[one-to-many] associations, link:http://www.datanucleus.org/products/accessplatform_4_1/jdo/orm/many_to_one.html[many-to-one] associations, link:http://www.datanucleus.org/products/accessplatform_4_1/jdo/orm/many_to_many.html[many-to-many] associations, and so on.
+
+Also, while JDO/DataNucleus itself supports `java.util.Map` as a collection type, this is not supported by Apache Isis.
+If you do wish to use this collection type, then annotate the getter with `@Programmatic` so that it is ignored by the Apache Isis framework.
+====
+
+
+
+== Value vs Reference Types
+
+Apache Isis can (currently) only provide a UI for collections of references.
+While you can use DataNucleus to persist collections/arrays of value types, such properties must be annotated as `@Programmatic` so that they are ignored by Apache Isis.
+
+If you want to visualize an array of value types in Apache Isis, then one option is to wrap value in a view model, as explained xref:../ugfun/ugfun.adoc#_ugbtb_hints-and-tips_simulating-collections-of-values[elsewhere].
+
+
+
+[[__ugfun_programming-model_collections_derived-collections]]
+== Derived Collections
+
+A derived collection is simply a getter (no setter) that returns a `java.util.Collection` (or subtype).
+
+While derived properties and derived collections typically "walk the graph" to associated objects, there is nothing to prevent the returned value being the result of invoking a repository (domain service) action.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+    ...
+    public List<Order> getMostRecentOrders() {
+        return orderRepo.findMostRecentOrders(this, 5);
+    }
+}
+----
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-entities.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-entities.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-entities.adoc
new file mode 100644
index 0000000..ad2bd72
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-entities.adoc
@@ -0,0 +1,89 @@
+[[_ugfun_programming-model_domain-entities]]
+= Domain Entities
+: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/
+
+
+
+Entities are persistent domain objects, with their persistence handled by JDO/DataNucleus.
+As such, they are mapped to a persistent object store, typically an RDBMS, with DataNucleus taking care of both lazy loading and also the persisting of modified ("dirty") objects.
+
+Domain entities are generally decorated with both DataNucleus and Apache Isis annotations.
+The following is typical:
+
+[source,java]
+----
+@javax.jdo.annotations.PersistenceCapable(                                      // <1>
+        identityType=IdentityType.DATASTORE,                                    // <2>
+        schema = "simple",                                                      // <3>
+        table = "SimpleObject"
+)
+@javax.jdo.annotations.DatastoreIdentity(                                       // <4>
+        strategy=javax.jdo.annotations.IdGeneratorStrategy.IDENTITY,
+        column="id"
+)
+@javax.jdo.annotations.Version(                                                 // <5>
+        strategy= VersionStrategy.DATE_TIME,
+        column="version"
+)
+@javax.jdo.annotations.Queries({
+        @javax.jdo.annotations.Query(                                           // <6>
+                name = "findByName",
+                value = "SELECT "
+                        + "FROM domainapp.modules.simple.dom.impl.SimpleObject "
+                        + "WHERE name.indexOf(:name) >= 0 ")
+})
+@javax.jdo.annotations.Unique(name="SimpleObject_name_UNQ", members = {"name"}) // <7>
+@DomainObject(                                                                  // <8>
+        objectType = "simple.SimpleObject"
+)
+public class SimpleObject
+             implements Comparable<SimpleObject> {                              // <9>
+
+    public SimpleObject(final String name) {                                    // <10>
+        setName(name);
+    }
+
+    ...
+
+    @Override
+    public String toString() {
+        return ObjectContracts.toString(this, "name");                          // <11>
+    }
+    @Override
+    public int compareTo(final SimpleObject other) {
+        return ObjectContracts.compare(this, other, "name");                    // <9>
+    }
+}
+----
+<1> The `@PersistenceCapable` annotation indicates that this is an entity to DataNucleus.
+The DataNucleus enhancer acts on the bytecode of compiled entities, injecting lazy loading and dirty object tracking functionality.
+Enhanced entities end up also implementing the `javax.jdo.spi.PersistenceCapable` interface.
+<2> Indicates how identifiers for the entity are handled.
+Using `DATASTORE` means that a DataNucleus is responsible for assigning the value (rather than the application).
+<3> Specifies the RDBMS database schema and table name for this entity will reside.
+The schema should correspond with the module in which the entity resides.
+The table will default to the entity name if omitted.
+<4> For entities that are using `DATASTORE` identity, indicates how the id will be assigned.
+A common strategy is to allow the database to assign the id, for example using an identity column or a sequence.
+<5> The `@Version` annotation is useful for optimistic locking; the strategy indicates what to store in the `version` column.
+<6> The `@Query` annotation (usually several of them, nested within a `@Queries` annotation) defines queries using JDOQL.
+DataNucleus provides several APIs for defining queries, including entirely programmatic and type-safe APIs; but JDOQL is very similar to SQL and so easily learnt.
+<7> DataNucleus will automatically add a unique index to the primary surrogate id (discussed above), but additional alternative keys can be defined using the `@Unique` annotation.
+In the example above, the "name" property is assumed to be unique.
+<8> The `@DomainObject` annotation identifies the domain object to Apache Isis (not DataNucleus).
+It isn't necessary to include this annotation -- at least, not for entities -- but it is nevertheless recommended.
+In particular, its strongly recommended that the `objectType` (which acts like an alias to the concrete domain class) is specified; note that it corresponds to the schema/table for DataNucleus' `@PersistenceCapable` annotation.
+<9> Although not required, we strongly recommend that all entities are naturally `Comparable`.
+This then allows parent/child relationships to be defined using ``SortedSet``s; RDBMS after all are set-oriented.
+The `ObjectContracts` utility class provided by Apache Isis makes it easy to implement the `compareTo()` method, but you can also just use an IDE to generate an implementation or roll your own.
+<10> Chances are that some of the properties of the entity will be mandatory, for example any properties that represent an alternate unique key to the entity.
+In regular Java programming we would represent this using a constructor that defines these mandatory properties, and in Apache Isis/DataNucleus we can likewise define such a constructor.
+When DataNucleus rehydrates domain entities from the database at runtime, it actually requires a no-arg constructor (it then sets all state reflectively).
+However, there is no need to provide such a no-arg constructor; it is added by the enhancer process.
+<11> The `ObjectContracts` utility class also provides assistance for `toString()`, useful when debugging in an IDE.
+
+
+NOTE: FIXME - xref the ugodn guide for other mappings of persistent entities.
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services.adoc
new file mode 100644
index 0000000..68f8919
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services.adoc
@@ -0,0 +1,383 @@
+[[_ugfun_programming-model_domain-services]]
+= Domain Services
+: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/
+
+
+This section looks at the programming conventions of writing your own domain services.
+
+''''
+''''
+
+[[__ugfun_building-blocks_domain-services_organizing-services]]
+== Organizing Services
+
+In larger applications we have found it worthwhile to ensure that our domain services only act aligned with these responsibilities, employing a naming convention so that it is clear what the responsibilities of each domain service is.
+
+The application provides the `@DomainService(nature=...)` annotation that helps distinguish some of these responsibilities:
+
+- `VIEW` indicates that the actions should appear both on the menu and also be used as contributions
+- `VIEW_MENU_ONLY` indicates that the actions should appear on the menu
+- `VIEW_CONTRIBUTIONS_ONLY` indicates that the actions should not appear on the menu
+- `DOMAIN` indicates that the actions are for other domain objects to invoke (either directly or indirectly through the event bus), but in any case should not be rendered at all in the UI
+
+NOTE: FIXME - deprecate any mention of VIEW_CONTRIBUTIONS_ONLY
+
+Pulling all the above together, here are our suggestions as to how you should organize your domain services.
+
+NOTE: FIXME - instead, xref to progamming model sections
+
+
+
+
+== Prototyping
+
+While for long-term maintainability we do recommend the naming conventions described xref:../ugfun/ugfun.adoc#__ugfun_building-blocks_domain-services_organizing-services[above], you can get away with far fewer services when just prototyping a domain.
+
+If the domain service nature is not specified (or is left to its default, `VIEW`), then the service's actions will
+appear in the UI both as menu items _and_ as contributions (and the service can of course be injected into other domain objects for programmatic invocation).
+
+Later on it is easy enough to refactor the code to tease apart the different responsibilities.
+
+
+
+
+
+''''
+''''
+
+
+== Typical Implementation
+
+Domain services are generally singletons that are automatically injected into other domain services.
+A very common usage is as a repository (to find/locate existing entities) or as a factory (to create new instances of entities).
+But services can also be exposed in the UI as top-level menus; and services are also used as a bridge to access technical resources (eg rendering a document object as a PDF).
+
+The Apache Isis framework itself also provides a large number of number of domain services, catalogued in the xref:../rgsvc/rgsvc.adoc#[Domain Services Reference Guide].
+Some of these are APIs (intended to be called by your application's own domain objects) and some are SPIs (implemented by your application and called by the framework, customising the way it works).
+
+The following is a typical menu service:
+
+[source,java]
+----
+@DomainService(                                                 // <1>
+        nature = NatureOfService.VIEW_MENU_ONLY
+)
+@DomainServiceLayout(                                           // <2>
+        named = "Simple Objects",
+        menuOrder = "10"
+)
+public class SimpleObjectMenu {
+
+    ...
+
+    @Action(semantics = SemanticsOf.SAFE)
+    @ActionLayout(bookmarking = BookmarkPolicy.AS_ROOT)
+    @MemberOrder(sequence = "2")
+    public List<SimpleObject> findByName(                       // <3>
+            @ParameterLayout(named="Name")
+            final String name
+    ) {
+        return simpleObjectRepository.findByName(name);
+    }
+
+    @javax.inject.Inject
+    SimpleObjectRepository simpleObjectRepository;              // <4>
+}
+----
+<1> The (Apache Isis) `@DomainService` annotation is used to identify the class as a domain service.
+Apache Isis scans the classpath looking for classes with this annotation, so there very little configuration other than to tell the framework which packages to scan underneath.
+The `VIEW_MENU_ONLY` nature indicates that this service's actions should be exposed as menu items.
+<2> The (Apache Isis) `@DomainServiceLayout` annotation provides UI hints.
+In the example above the menu is named "Simple Objects" (otherwise it would have defaulted to "Simple Object Menu", based on the class name, while the `menuOrder` attribute determines the order of the menu with respect to other menu services.
+<3> The `findByName` method is annotated with various Apache Isis annotations (`@Action`, `@ActionLayout` and `@MemberOrder`) and is itself rendered in the UI as a "Find By Name" menu item underneath the "Simple Objects" menu.
+The implementation delegates to an `SimpleObjectRepository` service, which is injected.
+<4> The `javax.inject.Inject` annotation instructs Apache Isis framework to inject the `SimpleObjectRepository` service into this domain object.
+The framework can inject into not just other domain services but will also automatically into domain entities and view models.
+There is further discussion of service injection xref:../ugfun/ugfun.adoc#_ugfun_programming-model_inject-services[below].
+
+
+
+''''
+''''
+
+
+
+[[__ugfun_building-blocks_domain-services_factory-and-repository]]
+== Factory and Repository
+
+The factory/repository uses an injected xref:../rgsvc/rgsvc.adoc#_rgsvc_api_RepositoryService[`RepositoryService`] to both instantiate new objects and to query the database for existing objects of a given entity type.  It is not visible in UI, rather other services delegate to it.
+
+We suggest naming such classes `XxxRepository`, eg:
+
+
+[source,java]
+----
+@DomainService(
+    nature=NatureOfService.DOMAIN                               // <1>
+)
+public CustomerRepository {
+    public List<Customer> findCustomerBy...(...) {
+        return repositoyService.allMatches(...);
+    }
+    public Customer newCustomer(...) {
+        Customer Customer = container.newTransientInstance(Customer.class);
+        ...
+        persistIfNotAlready(Customer);
+        return Customer;
+    }
+    public List<Customer> allCustomers() {
+        return repositoryService.allInstances(Customer.class);
+    }
+    @Inject
+    RepositoryService repositoryService;
+}
+----
+<1> interacted with only programmatically by other objects in the domain layer.
+
+There is no need to annotate the actions; they are implicitly hidden because of the domain service's nature.
+
+
+[[__ugfun_building-blocks_domain-services_menu]]
+== Menu
+
+Menu services provide actions to be rendered on the menu.
+
+For the Wicket viewer, each service's actions appear as a collection of menu items of a named menu, and this menu is on one of the three menu bars provided by the Wicket viewer.  It is possible for more than one menu service's actions to appear on the same menu; a separator is shown between each.
+
+For the Restful Objects viewer, all menu services are shown in the services representation.
+
+We suggest naming such classes `XxxMenu`, eg:
+
+
+[source,java]
+----
+@DomainService(
+    nature = NatureOfService.VIEW_MENU_ONLY                     // <1>
+)
+@DomainServiceLayout(
+        named = "Customers",                                    // <2>
+        menuBar = DomainServiceLayout.MenuBar.PRIMARY,
+        menuOrder = "10"
+)
+public class CustomerMenu {
+    @Action(
+            semantics = SemanticsOf.SAFE
+    )
+    @MemberOrder( sequence = "1" )
+    public List<Customer> findCustomerBy...(...) {
+        return customerRepository.findCustomerBy(...);          // <3>
+    }
+
+    @Action(
+            semantics = SemanticsOf.NON_IDEMPOTENT
+    )
+    @MemberOrder( sequence = "3" )
+    public Customer newCustomer(...) {
+        return customerRepository.newCustomer(...);
+    }
+
+    @Action(
+            semantics = SemanticsOf.SAFE,
+            restrictTo = RestrictTo.PROTOTYPING
+    )
+    @MemberOrder( sequence = "99" )
+    public List<Customer> allCustomers() {
+        return customerRepository.allBankMandates();
+    }
+
+    @Inject
+    protected CustomerRepository customerRepository;
+}
+----
+<1> the service's actions should be rendered as menu items
+<2> specifies the menu name.  All services with the same menu name will be displayed on the same menu, with separators between
+<3> delegates to an injected repository.
+
+Not every action on the repository need to be delegated to of course (the above example does but only because it is very simple).
+
+[TIP]
+====
+Note also that while there's nothing to stop `VIEW_MENU` domain services being injected into other domain objects and interacted with programmatically, we recommend against it.  Instead, inject the underlying repository.  If there is additional business logic, then consider introducing a further `DOMAIN`-scoped service and call that instead.
+====
+
+
+
+[[__ugfun_building-blocks_domain-services_contributions]]
+== Contributions (deprecated)
+
+
+Services can contribute either actions, properties or collections, based on the type of their parameters.
+
+[TIP]
+====
+Contributed services can instead be implemented as
+xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_mixins[mixins].
+As such, contributed services should be considered as deprecated.
+====
+
+We suggest naming such classes `XxxContributions`, eg:
+
+[source,java]
+----
+@DomainService(
+    nature=NatureOfService.VIEW_CONTRIBUTIONS_ONLY              // <1>
+)
+@DomainServiceLayout(
+    menuOrder="10",
+    name="...",
+}
+public class OrderContributions {
+    @Action(semantics=SemanticsOf.SAFE)
+    @ActionLayout(contributed=Contributed.AS_ASSOCIATION)       // <2>
+    @CollectionLayout(render=RenderType.EAGERLY)
+    public List<Order> orders(Customer customer) {              // <3>
+        return container.allMatches(...);
+    }
+
+    @Inject
+    CustomerRepository customerRepository;
+}
+----
+<1> the service's actions should be contributed to the entities of the parameters of those actions
+<2> contributed as an association, in particular as a collection because returns a `List<T>`.
+<3> Only actions with a single argument can be contributed as associations
+
+More information about contributions can be found xref:../ugfun/ugfun.adoc#_ugfun_how-tos_contributed-members[here].  More information
+about using contributions and mixins to keep your domain application decoupled can be found xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_contributions[here] and xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_mixins[here].
+
+
+
+
+[[__ugfun_building-blocks_domain-services_event-subscribers]]
+== Event Subscribers
+
+NOTE: FIXME - use AbstractSubscriber, need to show how to subscribe with event service bus...
+
+Event subscribers can both veto interactions (hiding members, disabling members or validating changes), or can react to interactions (eg action invocation or property edit).
+
+We suggest naming such classes `XxxSubscriptions`, eg:
+
+[source,java]
+----
+@DomainService(
+    nature=NatureOfService.DOMAIN                       // <1>
+)
+@DomainServiceLayout(
+    menuOrder="10",
+    name="...",
+}
+public class CustomerOrderSubscriptions {
+    @com.google.common.eventbus.Subscribe
+    public void on(final Customer.DeletedEvent ev) {
+        Customer customer = ev.getSource();
+        orderRepository.delete(customer);
+    }
+    @Inject
+    OrderRepository orderRepository;
+}
+----
+<1> subscriptions do not appear in the UI at all, so should use the domain nature of service
+
+
+
+
+''''
+''''
+
+
+
+== Scoped services
+
+By default all domain services are considered to be singletons, and thread-safe.
+
+Sometimes though a service's lifetime is applicable only to a single request; in other words it is request-scoped.
+
+The CDI annotation xref:../rgant/rgant.adoc#_rgant-RequestScoped[`@javax.enterprise.context.RequestScoped`] is used to indicate this fact:
+
+[source,java]
+----
+@javax.enterprise.context.RequestScoped
+public class MyService extends AbstractService {
+    ...
+}
+----
+
+The framework provides a number of request-scoped services, include a xref:../rgsvc/rgsvc.adoc#_rgsvc_api_Scratchpad[`Scratchpad`] service query results caching through the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_QueryResultsCache[`QueryResultsCache`], and support for co-ordinating bulk actions through the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ActionInvocationContext[`ActionInvocationContext`] service.  See the xref:../rgsvc/rgsvc.adoc[domain services] reference guide for further details.
+
+
+
+
+== Registering domain services
+
+The easiest way to register domain services is using xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`] to specify the modules
+which contain xref:../rgant/rgant.adoc#_rgant-DomainService[`@DomainService`]-annotated classes.
+
+For example:
+
+[source,ini]
+----
+public class MyAppManifest implements AppManifest {
+    public List<Class<?>> getModules() {
+        return Arrays.asList(
+                ToDoAppDomainModule.class,
+                ToDoAppFixtureModule.class,
+                ToDoAppAppModule.class,
+                org.isisaddons.module.audit.AuditModule.class);
+    }
+    ...
+}
+----
+
+will load all services in the packages underneath the four modules listed.
+
+An alternative (older) mechanism is to registered domain services in the `isis.properties` configuration file, under `isis.services` key (a comma-separated list); for example:
+
+[source,ini]
+----
+isis.services = com.mycompany.myapp.employee.Employees\,
+                com.mycompany.myapp.claim.Claims\,
+                ...
+----
+
+This will then result in the framework instantiating a single instance of each of the services listed.
+
+If all services reside under a common package, then the `isis.services.prefix` can specify this prefix:
+
+[source,ini]
+----
+isis.services.prefix = com.mycompany.myapp
+isis.services = employee.Employees,\
+                claim.Claims,\
+                ...
+----
+
+This is quite rare, however; you will often want to use default implementations of domain services that are provided by the framework and so will not reside under this prefix.
+
+Examples of framework-provided services (as defined in the applib) include clock, auditing, publishing, exception handling, view model support, snapshots/mementos, and user/application settings management; see the xref:../rgsvc/rgsvc.adoc[domain services] reference guide for further details.
+
+
+
+== Initialization
+
+Services can optionally declare lifecycle callbacks to initialize them (when the app is deployed) and to shut them down (when the app is undeployed).
+
+An Apache Isis session _is_ available when initialization occurs (so services can interact with the object store, for example).
+
+
+The framework will call any `public` method annotated with xref:../rgant/rgant.adoc#_rgant-PostConstruct[`@PostConstruct`] with either no arguments of an argument of type `Map<String,String>`
+
+or
+
+In the latter case, the framework passes in the configuration (`isis.properties` and any other component-specific configuration files).
+
+
+Shutdown is similar; the framework will call any method annotated with xref:../rgant/rgant.adoc#_rgant-PreDestroy[`@PreDestroy`].
+
+
+
+== The getId() method
+
+Optionally, a service may provide a xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_getId[`getId()`] method.  This method returns a logical identifier for a service, independent of its implementation.
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_inject-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_inject-services.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_inject-services.adoc
new file mode 100644
index 0000000..1e23b09
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_inject-services.adoc
@@ -0,0 +1,103 @@
+[[_ugfun_programming-model_inject-services]]
+= Injecting services
+: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 autowires (automatically injects) domain services into each entity, as well as into the domain services themselves, using either method injection or field injection.
+The framework defines many additional services (such as xref:../rgsvc/rgsvc.adoc#_rgsvc_api_RepositoryService[`RepositoryService`]); these are injected in exactly the same manner.
+
+Sometimes there may be multiple services that implement a single type.
+This is common for example for SPI service, whereby one module defines an SPI service, and other module(s) in the application implement that service.
+To support this, the framework also allows lists of services to be injected.
+
+When there are multiple service implementations of a given type, the framework will inject the service with highest priority, as defined through xref:../rgant/rgant.adoc#_rgant_DomainService_menuOrder[`@DomainService#menuOrder()`] (even for domain services that are not menus), lowest first.
+If a list of services is injected, then that list will be ordered according to `menuOrder`, again lowest first.
+
+
+
+[NOTE]
+====
+Isis currently does _not_ support qualified injection of services; the domain service of each type must be distinct from any other.
+
+If you find a requirement to inject two instances of type `SomeService`, say, then the work-around is to create trivial subclasses `SomeServiceA` and `SomeServiceB` and inject these instead.
+====
+
+
+== Field Injection
+
+Field injection is recommended, using the `@javax.inject.Inject` annotation.
+For example:
+
+[source,java]
+----
+public class Customer {
+    ...
+    @javax.inject.Inject
+    OrderRepository orderRepository;
+}
+----
+
+To inject a list of services, use:
+
+[source,java]
+----
+public class DocumentService {
+    ...
+    @javax.inject.Inject
+    List<PaperclipFactory> paperclipFactories;
+}
+----
+
+We recommend using default rather than `private` visibility so that the field can be mocked out within unit tests (placed in the same package as the code under test).
+
+
+
+
+== Method Injection
+
+The framework also supports two forms of method injection.
+All that is required to inject a service into a entity/service is to provide an appropriate method or field.
+The name of the method does not matter, only that it is prefixed either `set` or `inject`, is public, and has a single parameter of the correct type.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+    private OrderRepository orderRepository;
+    public void setOrderRepository(OrderRepository orderRepository) {
+        this.orderRepository = orderRepository;
+    }
+    ...
+}
+----
+
+or alternatively, using 'inject' as the prefix:
+
+[source,java]
+----
+public class Customer {
+    private OrderRepository orderRepository;
+    public void injectOrderRepository(OrderRepository orderRepository) {
+        this.orderRepository = orderRepository;
+    }
+    ...
+}
+----
+
+Lists of services can be injected in a similar manner.
+
+Note that the method name can be anything; it doesn't need to be related to the type being injected.
+
+
+== Constructor injection
+
+Simply to note that constructor injection is _not_ supported by Apache Isis (and is unlikely to be, because the JDO specification for entities requires a no-arg constructor).
+
+
+
+
+
+

[43/58] [abbrv] isis git commit: ISIS-1521: reorganizes ugfun.adoc, to get rid of 'how-to' chaptergs

[da...@apache.org]

ISIS-1521: reorganizes ugfun.adoc, to get rid of 'how-to' chaptergs


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/9fbf3d54
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/9fbf3d54
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/9fbf3d54

Branch: refs/heads/wip
Commit: 9fbf3d545ed95bcde8d9380cbcb472952c5990a2
Parents: 480d6ff
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Sat Apr 15 10:35:43 2017 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Thu Apr 20 09:09:30 2017 +0100

----------------------------------------------------------------------
 .../_ugfun_domain-class-ontology_mixins.adoc    | 54 ++++++++++++++++++++
 1 file changed, 54 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/9fbf3d54/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_mixins.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_mixins.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_mixins.adoc
new file mode 100644
index 0000000..abecbd5
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_mixins.adoc
@@ -0,0 +1,54 @@
+[[_ugfun_domain-class-ontology_mixins]]
+= Mixins
+: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/
+
+
+
+A mixin object allows one class to contribute behaviour - actions, (derived) properties and (derived) collections - to another domain object, either a domain entity or view model.
+
+Some programming languages use the term "trait" instead of mixin, and some languages (such as AspectJ) define their own syntax for defining such constructs.
+In Apache Isis a mixin is very similar to a domain service, however it also defines a single 1-arg constructor that defines the type of the domain objects that it contributes to.
+
+Why do this?
+Two reasons:
+
+* The main reason is to allow the app to be decoupled, so that it doesn't degrade into the proverbial link:http://www.laputan.org/mud/mud.html#BigBallOfMud["big ball of mud"].
+Mixins (and contributions) allow dependency to be inverted, so that the dependencies between modules can be kept acyclic and under control.
+
+* However, there is another reason: mixins are also a convenient mechanism for grouping functionality even for a concrete type, helping to rationalize about the dependency between the data and the behaviour.
+
+Both use cases are discussed below.
+
+Syntactically, a mixin is defined using either the xref:../rgant/rgant.adoc#_rgant_Mixin[`@Mixin`] annotation or using xref:../rgant/rgant.adoc#_rgant_DomainObject_nature[`@DomainObject#nature()`] attribute (specifying a nature of `Nature.MIXIN`).
+
+
+
+[source,java]
+----
+@Mixin(method="coll")                                       // <1>
+public class Customer_orders {                              // <2>
+
+    private final Customer customer;
+    public Customer_orders(final Customer customer) {       // <3>
+        this.customer = customer;
+    }
+
+    @Action(semantics=SemanticsOf.SAFE)                     // <4>
+    @ActionLayout(contributed=Contributed.AS_ASSOCIATION)   // <4>
+    @CollectionLayout(render=RenderType.EAGERLY)
+    public List<Order> coll() {                             // <1>
+        return repositoryService.findOrdersFor(customer);
+    }
+
+    @Inject
+    RepositoryService repositoryService;
+}
+----
+<1> indicates that this is a mixin, with "coll" as the name of the main method
+<2> The contributed member is inferred from the name, after the "_"; in other words "orders"
+<3> The mixee is `Customer`.
+This could also be an interface.
+<4> Indicates that the action should be interpreted as a collection.
+This requires that the action has safe semantics, ie does not alter state/no side-effects.

[18/58] [abbrv] isis git commit: ISIS-1521: more reorganizing of images and also resources for dg.adoc

[da...@apache.org]

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/200-project-sdk/040-set-project-level.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/200-project-sdk/040-set-project-level.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/200-project-sdk/040-set-project-level.png
deleted file mode 100644
index 026a821..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/200-project-sdk/040-set-project-level.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/200-project-sdk/050-isis-language-level-7.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/200-project-sdk/050-isis-language-level-7.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/200-project-sdk/050-isis-language-level-7.png
deleted file mode 100644
index 62e220b..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/200-project-sdk/050-isis-language-level-7.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/200-project-sdk/060-app-language-level-8.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/200-project-sdk/060-app-language-level-8.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/200-project-sdk/060-app-language-level-8.png
deleted file mode 100644
index 5723524..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/200-project-sdk/060-app-language-level-8.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/250-new-project/010-new-project.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/250-new-project/010-new-project.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/250-new-project/010-new-project.png
deleted file mode 100644
index edc97cf..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/250-new-project/010-new-project.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/250-new-project/020-new-project-name.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/250-new-project/020-new-project-name.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/250-new-project/020-new-project-name.png
deleted file mode 100644
index 15b78a7..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/250-new-project/020-new-project-name.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/250-new-project/030-new-project-new-window.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/250-new-project/030-new-project-new-window.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/250-new-project/030-new-project-new-window.png
deleted file mode 100644
index b8d8e61..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/250-new-project/030-new-project-new-window.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/250-new-project/040-new-module-from-existing-sources.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/250-new-project/040-new-module-from-existing-sources.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/250-new-project/040-new-module-from-existing-sources.png
deleted file mode 100644
index 160b3b9..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/250-new-project/040-new-module-from-existing-sources.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/250-new-project/050-specify-source-folder.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/250-new-project/050-specify-source-folder.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/250-new-project/050-specify-source-folder.png
deleted file mode 100644
index 5eecb9c..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/250-new-project/050-specify-source-folder.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/250-new-project/060-import-using-maven.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/250-new-project/060-import-using-maven.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/250-new-project/060-import-using-maven.png
deleted file mode 100644
index 55a5db3..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/250-new-project/060-import-using-maven.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/250-new-project/070-import-module-settings.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/250-new-project/070-import-module-settings.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/250-new-project/070-import-module-settings.png
deleted file mode 100644
index 6828802..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/250-new-project/070-import-module-settings.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/250-new-project/080-maven-profiles.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/250-new-project/080-maven-profiles.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/250-new-project/080-maven-profiles.png
deleted file mode 100644
index fcc12aa..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/250-new-project/080-maven-profiles.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/250-new-project/090-maven-coordinates.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/250-new-project/090-maven-coordinates.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/250-new-project/090-maven-coordinates.png
deleted file mode 100644
index fc6691f..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/250-new-project/090-maven-coordinates.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/250-new-project/100-annotation-processing.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/250-new-project/100-annotation-processing.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/250-new-project/100-annotation-processing.png
deleted file mode 100644
index dbb7b6a..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/250-new-project/100-annotation-processing.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/250-new-project/110-parameter8.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/250-new-project/110-parameter8.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/250-new-project/110-parameter8.png
deleted file mode 100644
index a7c4d8d..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/250-new-project/110-parameter8.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/250-new-project/120-clean-generate-sources.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/250-new-project/120-clean-generate-sources.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/250-new-project/120-clean-generate-sources.png
deleted file mode 100644
index 5a9182b..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/250-new-project/120-clean-generate-sources.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/300-paraname8-support/010-configuring-the-compiler.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/300-paraname8-support/010-configuring-the-compiler.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/300-paraname8-support/010-configuring-the-compiler.png
deleted file mode 100644
index 50a043f..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/300-paraname8-support/010-configuring-the-compiler.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/400-running-integtests/run-debug-configuration-single-module.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/400-running-integtests/run-debug-configuration-single-module.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/400-running-integtests/run-debug-configuration-single-module.png
deleted file mode 100644
index ca0bb13..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/images/appendices/dev-env/intellij-idea/400-running-integtests/run-debug-configuration-single-module.png and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/eclipse/eclipse-010-windows-preferences.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/eclipse/eclipse-010-windows-preferences.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/eclipse/eclipse-010-windows-preferences.png
new file mode 100644
index 0000000..149a23b
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/eclipse/eclipse-010-windows-preferences.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/eclipse/eclipse-025-project-properties.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/eclipse/eclipse-025-project-properties.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/eclipse/eclipse-025-project-properties.png
new file mode 100644
index 0000000..120856c
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/eclipse/eclipse-025-project-properties.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/eclipse/eclipse-100-project-support.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/eclipse/eclipse-100-project-support.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/eclipse/eclipse-100-project-support.png
new file mode 100644
index 0000000..7068fb4
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/eclipse/eclipse-100-project-support.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/eclipse/eclipse-110-project-support.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/eclipse/eclipse-110-project-support.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/eclipse/eclipse-110-project-support.png
new file mode 100644
index 0000000..49d04a8
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/eclipse/eclipse-110-project-support.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/eclipse/eclipse-120-console.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/eclipse/eclipse-120-console.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/eclipse/eclipse-120-console.png
new file mode 100644
index 0000000..1e77587
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/eclipse/eclipse-120-console.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/eclipse/eclipse-200-enhancer-fails-duplicates.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/eclipse/eclipse-200-enhancer-fails-duplicates.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/eclipse/eclipse-200-enhancer-fails-duplicates.png
new file mode 100644
index 0000000..8d7e10a
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/eclipse/eclipse-200-enhancer-fails-duplicates.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/eclipse/eclipse-210-enhancer-fails-duplicates.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/eclipse/eclipse-210-enhancer-fails-duplicates.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/eclipse/eclipse-210-enhancer-fails-duplicates.png
new file mode 100644
index 0000000..5350251
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/eclipse/eclipse-210-enhancer-fails-duplicates.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/eclipse/eclipse-220-enhancer-fails-duplicates.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/eclipse/eclipse-220-enhancer-fails-duplicates.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/eclipse/eclipse-220-enhancer-fails-duplicates.png
new file mode 100644
index 0000000..dbe247e
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/eclipse/eclipse-220-enhancer-fails-duplicates.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/010-installing/010-welcome-page.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/010-installing/010-welcome-page.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/010-installing/010-welcome-page.png
new file mode 100644
index 0000000..24fbed3
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/010-installing/010-welcome-page.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/010-installing/020-choose-location.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/010-installing/020-choose-location.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/010-installing/020-choose-location.png
new file mode 100644
index 0000000..1d0cb46
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/010-installing/020-choose-location.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/010-installing/030-installation-options.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/010-installing/030-installation-options.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/010-installing/030-installation-options.png
new file mode 100644
index 0000000..01fbe56
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/010-installing/030-installation-options.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/010-installing/040-start-menu-folder.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/010-installing/040-start-menu-folder.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/010-installing/040-start-menu-folder.png
new file mode 100644
index 0000000..dc850cc
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/010-installing/040-start-menu-folder.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/010-installing/050-completing.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/010-installing/050-completing.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/010-installing/050-completing.png
new file mode 100644
index 0000000..7b80e17
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/010-installing/050-completing.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/010-installing/060-import-settings-or-not.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/010-installing/060-import-settings-or-not.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/010-installing/060-import-settings-or-not.png
new file mode 100644
index 0000000..0054c4c
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/010-installing/060-import-settings-or-not.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/010-installing/070-set-ui-theme.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/010-installing/070-set-ui-theme.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/010-installing/070-set-ui-theme.png
new file mode 100644
index 0000000..247fc64
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/010-installing/070-set-ui-theme.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/020-create-new-project/010-new-project-create.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/020-create-new-project/010-new-project-create.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/020-create-new-project/010-new-project-create.png
new file mode 100644
index 0000000..a950887
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/020-create-new-project/010-new-project-create.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/020-create-new-project/020-java-project-setup-jdk.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/020-create-new-project/020-java-project-setup-jdk.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/020-create-new-project/020-java-project-setup-jdk.png
new file mode 100644
index 0000000..16fe8d1
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/020-create-new-project/020-java-project-setup-jdk.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/020-create-new-project/030-java-project-select-jdk.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/020-create-new-project/030-java-project-select-jdk.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/020-create-new-project/030-java-project-select-jdk.png
new file mode 100644
index 0000000..d0214c6
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/020-create-new-project/030-java-project-select-jdk.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/020-create-new-project/040-sdk-selected.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/020-create-new-project/040-sdk-selected.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/020-create-new-project/040-sdk-selected.png
new file mode 100644
index 0000000..b9399d6
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/020-create-new-project/040-sdk-selected.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/020-create-new-project/050-name-and-location.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/020-create-new-project/050-name-and-location.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/020-create-new-project/050-name-and-location.png
new file mode 100644
index 0000000..7f3b8d6
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/020-create-new-project/050-name-and-location.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/020-create-new-project/060-create-dir.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/020-create-new-project/060-create-dir.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/020-create-new-project/060-create-dir.png
new file mode 100644
index 0000000..287478a
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/020-create-new-project/060-create-dir.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/030-import-settings/010-settings-import-jar.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/030-import-settings/010-settings-import-jar.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/030-import-settings/010-settings-import-jar.png
new file mode 100644
index 0000000..be6fb1e
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/030-import-settings/010-settings-import-jar.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/030-import-settings/020-select-all.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/030-import-settings/020-select-all.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/030-import-settings/020-select-all.png
new file mode 100644
index 0000000..8e63a35
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/030-import-settings/020-select-all.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/030-import-settings/030-restart.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/030-import-settings/030-restart.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/030-import-settings/030-restart.png
new file mode 100644
index 0000000..c20e0ac
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/030-import-settings/030-restart.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/030-import-settings/040-file-templates.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/030-import-settings/040-file-templates.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/030-import-settings/040-file-templates.png
new file mode 100644
index 0000000..c238509
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/030-import-settings/040-file-templates.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/030-import-settings/050-live-templates.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/030-import-settings/050-live-templates.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/030-import-settings/050-live-templates.png
new file mode 100644
index 0000000..6fc56ba
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/030-import-settings/050-live-templates.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/040-other-settings-compiler/010-build-automatically.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/040-other-settings-compiler/010-build-automatically.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/040-other-settings-compiler/010-build-automatically.png
new file mode 100644
index 0000000..b383b3c
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/040-other-settings-compiler/010-build-automatically.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/040-other-settings-compiler/020-annotation-processor.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/040-other-settings-compiler/020-annotation-processor.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/040-other-settings-compiler/020-annotation-processor.png
new file mode 100644
index 0000000..7618a4d
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/040-other-settings-compiler/020-annotation-processor.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/042-other-settings-maven/010-maven-installation.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/042-other-settings-maven/010-maven-installation.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/042-other-settings-maven/010-maven-installation.png
new file mode 100644
index 0000000..9fef693
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/042-other-settings-maven/010-maven-installation.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/042-other-settings-maven/020-maven-configuration.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/042-other-settings-maven/020-maven-configuration.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/042-other-settings-maven/020-maven-configuration.png
new file mode 100644
index 0000000..945968d
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/042-other-settings-maven/020-maven-configuration.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/044-other-settings-misc/010-auto-import.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/044-other-settings-misc/010-auto-import.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/044-other-settings-misc/010-auto-import.png
new file mode 100644
index 0000000..293d2c3
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/044-other-settings-misc/010-auto-import.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/050-some-plugins/010-some-plugins.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/050-some-plugins/010-some-plugins.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/050-some-plugins/010-some-plugins.png
new file mode 100644
index 0000000..9e2230b
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/050-some-plugins/010-some-plugins.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/050-some-plugins/020-some-plugins-confirmation.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/050-some-plugins/020-some-plugins-confirmation.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/050-some-plugins/020-some-plugins-confirmation.png
new file mode 100644
index 0000000..037c967
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/050-some-plugins/020-some-plugins-confirmation.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/050-some-plugins/maven-helper/010-dependency-tab.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/050-some-plugins/maven-helper/010-dependency-tab.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/050-some-plugins/maven-helper/010-dependency-tab.png
new file mode 100644
index 0000000..a42b430
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/050-some-plugins/maven-helper/010-dependency-tab.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/050-some-plugins/maven-helper/020-dependency-as-tree.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/050-some-plugins/maven-helper/020-dependency-as-tree.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/050-some-plugins/maven-helper/020-dependency-as-tree.png
new file mode 100644
index 0000000..15ae90b
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/050-some-plugins/maven-helper/020-dependency-as-tree.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/050-some-plugins/maven-helper/030-maven-run-goal.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/050-some-plugins/maven-helper/030-maven-run-goal.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/050-some-plugins/maven-helper/030-maven-run-goal.png
new file mode 100644
index 0000000..e8a6d1e
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/050-some-plugins/maven-helper/030-maven-run-goal.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/050-some-plugins/maven-helper/040-maven-quick-run.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/050-some-plugins/maven-helper/040-maven-quick-run.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/050-some-plugins/maven-helper/040-maven-quick-run.png
new file mode 100644
index 0000000..f3a6d67
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/050-some-plugins/maven-helper/040-maven-quick-run.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/060-troubleshooting/010-duplicate-classes.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/060-troubleshooting/010-duplicate-classes.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/060-troubleshooting/010-duplicate-classes.png
new file mode 100644
index 0000000..1d6d6c3
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/060-troubleshooting/010-duplicate-classes.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/070-advanced/002-compiler-exclude.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/070-advanced/002-compiler-exclude.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/070-advanced/002-compiler-exclude.png
new file mode 100644
index 0000000..ba9cb59
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/070-advanced/002-compiler-exclude.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/070-advanced/004-gradle-output.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/070-advanced/004-gradle-output.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/070-advanced/004-gradle-output.png
new file mode 100644
index 0000000..023538d
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/070-advanced/004-gradle-output.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/070-advanced/005-gradle-output.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/070-advanced/005-gradle-output.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/070-advanced/005-gradle-output.png
new file mode 100644
index 0000000..edaa8e5
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/070-advanced/005-gradle-output.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/070-advanced/006-livereload-js.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/070-advanced/006-livereload-js.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/070-advanced/006-livereload-js.png
new file mode 100644
index 0000000..f5d6a2b
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/070-advanced/006-livereload-js.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/070-advanced/010-dcevm-list-of-found-jdk-installations.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/070-advanced/010-dcevm-list-of-found-jdk-installations.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/070-advanced/010-dcevm-list-of-found-jdk-installations.png
new file mode 100644
index 0000000..601e418
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/070-advanced/010-dcevm-list-of-found-jdk-installations.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/070-advanced/020-dcevm-once-installed.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/070-advanced/020-dcevm-once-installed.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/070-advanced/020-dcevm-once-installed.png
new file mode 100644
index 0000000..afc39ea
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/070-advanced/020-dcevm-once-installed.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/070-advanced/030-dcevm-intellij-project-structure.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/070-advanced/030-dcevm-intellij-project-structure.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/070-advanced/030-dcevm-intellij-project-structure.png
new file mode 100644
index 0000000..951b4a6
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/070-advanced/030-dcevm-intellij-project-structure.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/070-advanced/040-dcevm-run-configuration.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/070-advanced/040-dcevm-run-configuration.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/070-advanced/040-dcevm-run-configuration.png
new file mode 100644
index 0000000..9d042f7
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/070-advanced/040-dcevm-run-configuration.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/100-maven-module-mgmt/010-maven-modules-view.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/100-maven-module-mgmt/010-maven-modules-view.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/100-maven-module-mgmt/010-maven-modules-view.png
new file mode 100644
index 0000000..a5b8944
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/100-maven-module-mgmt/010-maven-modules-view.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/100-maven-module-mgmt/020-adding-another-module.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/100-maven-module-mgmt/020-adding-another-module.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/100-maven-module-mgmt/020-adding-another-module.png
new file mode 100644
index 0000000..b8e9ba9
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/100-maven-module-mgmt/020-adding-another-module.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/100-maven-module-mgmt/030-other-module-added.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/100-maven-module-mgmt/030-other-module-added.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/100-maven-module-mgmt/030-other-module-added.png
new file mode 100644
index 0000000..58b42f0
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/100-maven-module-mgmt/030-other-module-added.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/100-maven-module-mgmt/040-ignoring-modules.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/100-maven-module-mgmt/040-ignoring-modules.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/100-maven-module-mgmt/040-ignoring-modules.png
new file mode 100644
index 0000000..0421f99
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/100-maven-module-mgmt/040-ignoring-modules.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/100-maven-module-mgmt/050-ignoring-modules-2.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/100-maven-module-mgmt/050-ignoring-modules-2.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/100-maven-module-mgmt/050-ignoring-modules-2.png
new file mode 100644
index 0000000..6bf26ac
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/100-maven-module-mgmt/050-ignoring-modules-2.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/100-maven-module-mgmt/060-ignored-modules.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/100-maven-module-mgmt/060-ignored-modules.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/100-maven-module-mgmt/060-ignored-modules.png
new file mode 100644
index 0000000..b16086b
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/100-maven-module-mgmt/060-ignored-modules.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/110-running-the-app/010-run-configuration.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/110-running-the-app/010-run-configuration.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/110-running-the-app/010-run-configuration.png
new file mode 100644
index 0000000..0c6a929
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/110-running-the-app/010-run-configuration.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/110-running-the-app/020-datanucleus-enhancer-goal.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/110-running-the-app/020-datanucleus-enhancer-goal.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/110-running-the-app/020-datanucleus-enhancer-goal.png
new file mode 100644
index 0000000..2dae157
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/110-running-the-app/020-datanucleus-enhancer-goal.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/110-running-the-app/030-running-unit-tests.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/110-running-the-app/030-running-unit-tests.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/110-running-the-app/030-running-unit-tests.png
new file mode 100644
index 0000000..b4e042a
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/110-running-the-app/030-running-unit-tests.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/110-running-the-app/040-running-unit-tests-run-configuration.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/110-running-the-app/040-running-unit-tests-run-configuration.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/110-running-the-app/040-running-unit-tests-run-configuration.png
new file mode 100644
index 0000000..83a4a70
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/110-running-the-app/040-running-unit-tests-run-configuration.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/110-running-the-app/050-running-integration-tests-run-configuration.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/110-running-the-app/050-running-integration-tests-run-configuration.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/110-running-the-app/050-running-integration-tests-run-configuration.png
new file mode 100644
index 0000000..6b0ad89
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/110-running-the-app/050-running-integration-tests-run-configuration.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/200-project-sdk/010-file-project-structure.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/200-project-sdk/010-file-project-structure.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/200-project-sdk/010-file-project-structure.png
new file mode 100644
index 0000000..544a185
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/200-project-sdk/010-file-project-structure.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/200-project-sdk/020-select-jdk.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/200-project-sdk/020-select-jdk.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/200-project-sdk/020-select-jdk.png
new file mode 100644
index 0000000..90865f1
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/200-project-sdk/020-select-jdk.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/200-project-sdk/030-select-jdk-directory.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/200-project-sdk/030-select-jdk-directory.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/200-project-sdk/030-select-jdk-directory.png
new file mode 100644
index 0000000..f5675b2
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/200-project-sdk/030-select-jdk-directory.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/200-project-sdk/040-set-project-level.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/200-project-sdk/040-set-project-level.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/200-project-sdk/040-set-project-level.png
new file mode 100644
index 0000000..026a821
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/200-project-sdk/040-set-project-level.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/200-project-sdk/050-isis-language-level-7.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/200-project-sdk/050-isis-language-level-7.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/200-project-sdk/050-isis-language-level-7.png
new file mode 100644
index 0000000..62e220b
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/200-project-sdk/050-isis-language-level-7.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/200-project-sdk/060-app-language-level-8.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/200-project-sdk/060-app-language-level-8.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/200-project-sdk/060-app-language-level-8.png
new file mode 100644
index 0000000..5723524
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/200-project-sdk/060-app-language-level-8.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/250-new-project/010-new-project.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/250-new-project/010-new-project.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/250-new-project/010-new-project.png
new file mode 100644
index 0000000..edc97cf
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/250-new-project/010-new-project.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/250-new-project/020-new-project-name.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/250-new-project/020-new-project-name.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/250-new-project/020-new-project-name.png
new file mode 100644
index 0000000..15b78a7
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/250-new-project/020-new-project-name.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/250-new-project/030-new-project-new-window.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/250-new-project/030-new-project-new-window.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/250-new-project/030-new-project-new-window.png
new file mode 100644
index 0000000..b8d8e61
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/250-new-project/030-new-project-new-window.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/250-new-project/040-new-module-from-existing-sources.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/250-new-project/040-new-module-from-existing-sources.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/250-new-project/040-new-module-from-existing-sources.png
new file mode 100644
index 0000000..160b3b9
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/250-new-project/040-new-module-from-existing-sources.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/250-new-project/050-specify-source-folder.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/250-new-project/050-specify-source-folder.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/250-new-project/050-specify-source-folder.png
new file mode 100644
index 0000000..5eecb9c
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/250-new-project/050-specify-source-folder.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/250-new-project/060-import-using-maven.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/250-new-project/060-import-using-maven.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/250-new-project/060-import-using-maven.png
new file mode 100644
index 0000000..55a5db3
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/250-new-project/060-import-using-maven.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/250-new-project/070-import-module-settings.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/250-new-project/070-import-module-settings.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/250-new-project/070-import-module-settings.png
new file mode 100644
index 0000000..6828802
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/250-new-project/070-import-module-settings.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/250-new-project/080-maven-profiles.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/250-new-project/080-maven-profiles.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/250-new-project/080-maven-profiles.png
new file mode 100644
index 0000000..fcc12aa
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/250-new-project/080-maven-profiles.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/250-new-project/090-maven-coordinates.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/250-new-project/090-maven-coordinates.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/250-new-project/090-maven-coordinates.png
new file mode 100644
index 0000000..fc6691f
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/250-new-project/090-maven-coordinates.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/250-new-project/100-annotation-processing.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/250-new-project/100-annotation-processing.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/250-new-project/100-annotation-processing.png
new file mode 100644
index 0000000..dbb7b6a
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/250-new-project/100-annotation-processing.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/250-new-project/110-parameter8.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/250-new-project/110-parameter8.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/250-new-project/110-parameter8.png
new file mode 100644
index 0000000..a7c4d8d
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/250-new-project/110-parameter8.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/250-new-project/120-clean-generate-sources.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/250-new-project/120-clean-generate-sources.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/250-new-project/120-clean-generate-sources.png
new file mode 100644
index 0000000..5a9182b
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/250-new-project/120-clean-generate-sources.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/300-paraname8-support/010-configuring-the-compiler.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/300-paraname8-support/010-configuring-the-compiler.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/300-paraname8-support/010-configuring-the-compiler.png
new file mode 100644
index 0000000..50a043f
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/300-paraname8-support/010-configuring-the-compiler.png differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/400-running-integtests/run-debug-configuration-single-module.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/400-running-integtests/run-debug-configuration-single-module.png b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/400-running-integtests/run-debug-configuration-single-module.png
new file mode 100644
index 0000000..ca0bb13
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/images/intellij-idea/400-running-integtests/run-debug-configuration-single-module.png differ

[44/58] [abbrv] isis git commit: ISIS-1521: further minor updates to ugfun.adoc

[da...@apache.org]

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_object-titles-and-icons.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_object-titles-and-icons.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_object-titles-and-icons.adoc
deleted file mode 100644
index 3a5b643..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_object-titles-and-icons.adoc
+++ /dev/null
@@ -1,97 +0,0 @@
-[[_ugfun_how-tos_ui-hints_object-titles-and-icons]]
-= Object Titles and Icons
-: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/
-
-
-In Apache Isis every object is identified to the user by a title (label) and an icon.  This is shown in several places: as the main heading for an object; as a link text for an object referencing another object, and also in tables representing collections of objects.
-
-The icon is often the same for all instances of a particular class, but it's also possible for an individual instance to return a custom icon.  This could represent the state of that object (eg a shipped order, say, or overdue library book).
-
-It is also possible for an object to provide a CSS class hint.  In conjunction with xref:../ugvw/ugvw.adoc#_ugvw_customisation_tweaking-css-classes[customized CSS] this can be used to apply arbitrary styling; for example each object could be rendered in a page with a different background colour.
-
-
-== Object Title
-
-The object title is a label to identify an object to the end-user.  Generally the object title is a label to identify an object to the end-user.  There is no requirement for it to be absolutely unique, but it should be "unique enough" to distinguish the object from other object's likely to be rendered on the same page.
-
-The title is always shown with an icon, so there is generally no need for the title to include information about the object's type.  For example the title of a customer object shouldn't include the literal string "Customer"; it can just have the customer's name, reference or some other meaningful business identifier.
-
-
-=== Declarative style
-
-The xref:../rgant/rgant.adoc#_rgant-Title[`@Title`] annotation can be used build up the title of an object from its constituent parts.
-
-For example:
-
-[source,java]
-----
-public class Customer {
-    @Title(sequence="1", append=" ")
-    public String getFirstName() { ... }
-    @Title(sequence="2")
-    public Product getLastName() { ... }
-    ...
-}
-----
-
-might return "Arthur Clarke", while:
-
-[source,java]
-----
-public class CustomerAlt {
-    @Title(sequence="2", prepend=", ")
-    public String getFirstName() { ... }
-
-    @Title(sequence="1")
-    public Product getLastName() { ... }
-    ...
-}
-----
-
-could return "Clarke, Arthur".
-
-Note that the sequence is in Dewey Decimal Format.  This allows a subclass to intersperse information within the title.  For example (please forgive this horrible domain modelling (!)):
-
-
-[source,java]
-----
-public class Author extends Customer {
-    @Title(sequence="1.5", append=". ")
-    public String getMiddleInitial() { ... }
-    ...
-}
-----
-
-could return "Arthur C. Clarke".
-
-
-[TIP]
-====
-Titles can sometimes get be long and therefore rather cumbersome in "parented" tables.  If `@Title` has been used then the Wicket viewer will automatically exclude portions of the title belonging to the owning object.
-====
-
-
-=== Imperative style
-
-NOTE: FIXME - see xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_title[`title()`]
-
-
-
-
-== Object Icon
-
-The icon is often the same for all instances of a particular class, but it's also possible for an individual instance to return a custom icon.  This could represent the state of that object (eg a shipped order, say, or overdue library book).
-
-NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`], xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_cssClassFa[`@DomainObjectLayout#cssClassFa()`]
-
-
-
-
-== Object CSS Styling
-
-
-It is also possible for an object to return a xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_cssClass[CSS class].  In conjunction with xref:../ugvw/ugvw.adoc#_ugvw_customisation_tweaking-css-classes[customized CSS] this can be used to apply arbitrary styling; for example each object could be rendered in a page with a different background colour.
-
-NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_cssClass[`cssClass()`], xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_cssClass[`@DomainObjectLayout#cssClass()`] xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout#cssClass()`], xref:../rgant/rgant.adoc#_rgant-PropertyLayout_cssClass[`@PropertyLayout#cssClass()`], xref:../rgant/rgant.adoc#_rgant-CollectionLayout_cssClass[`@CollectionLayout#cssClass()`]

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui_are-you-sure.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui_are-you-sure.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui_are-you-sure.adoc
deleted file mode 100644
index 7c24458..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui_are-you-sure.adoc
+++ /dev/null
@@ -1,76 +0,0 @@
-[[_ugfun_how-tos_ui_are-you-sure]]
-= 'Are you sure?' idiom
-: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/
-
-
-Sometimes an action might perform irreversible changes.  In such a case it's probably a good idea for the UI to require that the
-end-user explicitly confirms that they intended to invoke the action.
-
-== Using action semantics
-
-One way to meet this requirement is using the framework's built-in xref:../rgant/rgant.adoc#_rgant-Action_semantics[`@Action#semantics()`] attribute:
-
-[source,java]
-----
-@Action(
-        semantics = SemanticsOf.IDEMPOTENT_ARE_YOU_SURE
-)
-public SimpleObject updateName(
-        @Parameter(maxLength = NAME_LENGTH)
-        @ParameterLayout(named = "New name")
-        final String name) {
-    setName(name);
-    return this;
-}
-----
-
-
-This will render as:
-
-image::{_imagesdir}/how-tos/tips-n-tricks/action-semantics-are-you-sure.png[]
-
-
-== Using a checkbox
-
-An alternative approach (for all versions of the framework) is to require the end-user to check a dummy checkbox parameter (and prevent the action from being invoked if the user hasn't checked that parameter).
-
-For example:
-
-image::{_imagesdir}/how-tos/tips-n-tricks/are-you-sure.png[]
-
-[NOTE]
-====
-Note that these screenshots shows an earlier version of the xref:../ugvw/ugvw.adoc#[Wicket viewer] UI (specifically, pre 1.8.0).
-====
-
-If the user checks the box:
-
-image::{_imagesdir}/how-tos/tips-n-tricks/are-you-sure-happy-case.png[]
-
-then the action will complete.
-
-However, if the user fails to check the box, then a validation message is shown:
-
-image::{_imagesdir}/how-tos/tips-n-tricks/are-you-sure-sad-case.png[]
-
-
-
-The code for this is pretty simple:
-
-[source,java]
-----
-public List<ToDoItem> delete(@Named("Are you sure?") boolean areYouSure) {
-    container.removeIfNotAlready(this);
-    container.informUser("Deleted " + container.titleOf(this));
-    return toDoItems.notYetComplete();          // <1>
-}
-public String validateDelete(boolean areYouSure) {
-    return areYouSure? null: "Please confirm you are sure";
-}
-----
-<1> invalid to return `this` (cannot render a deleted object)
-
-Note that the action itself does not use the boolean parameter, it is only
-used by the supporting xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_validate[`validate...()`] method.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints.adoc
new file mode 100644
index 0000000..96c8c64
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints.adoc
@@ -0,0 +1,15 @@
+[[_ugfun_ui-hints]]
+= UI Hints
+: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/
+
+
+The Apache Isis programming model includes several mechanisms for a domain object to provide UI hints.  These range from their title (so an end-user can distinguish one object from another) through to hints that can impact their CSS styling.
+
+
+include::_ugfun_ui-hints_layout.adoc[leveloffset=+1]
+include::_ugfun_ui-hints_object-titles-and-icons.adoc[leveloffset=+1]
+include::_ugfun_ui-hints_names-and-descriptions.adoc[leveloffset=+1]
+include::_ugfun_ui-hints_eager-rendering.adoc[leveloffset=+1]
+include::_ugfun_ui-hints_action-icons-and-css.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_action-icons-and-css.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_action-icons-and-css.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_action-icons-and-css.adoc
new file mode 100644
index 0000000..b5f84bf
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_action-icons-and-css.adoc
@@ -0,0 +1,58 @@
+[[_ugfun_ui-hints_action-icons-and-css]]
+= Action Icons and CSS
+: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 allows link:http://fortawesome.github.io/Font-Awesome/icons/[font awesome] icons to be associated with each action, and for link:http://getbootstrap.com/css/#buttons[Bootstrap CSS] to be applied to action rendered as buttons.
+
+These UI hint can be applied either to individual actions, or can be applied en-masse using pattern matching.
+
+== Per action
+
+NOTE: FIXME - xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout#cssClass()`] and xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClassFa[`@ActionLayout#cssClassFa()`]
+
+
+Alternatively, you can specify these hints dynamically in the xref:../ugvw/ugvw.adoc#_ugvw_layout[`Xxx.layout.json`] for the entity.
+
+
+== Per pattern matching
+
+Rather than annotating every action with xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClassFa[`@ActionLayout#cssClassFa()`] and xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout#cssClass()`] you can instead specify the UI hint globally using regular expressions.
+
+The xref:../rgcfg/rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.reflector.facet.cssClassFa.patterns` is a comma separated list of key:value pairs, eg:
+
+[source,ini]
+----
+isis.reflector.facet.cssClassFa.patterns=\
+                        new.*:fa-plus,\
+                        add.*:fa-plus-square,\
+                        create.*:fa-plus,\
+                        list.*:fa-list, \
+                        all.*:fa-list, \
+                        download.*:fa-download, \
+                        upload.*:fa-upload, \
+                        execute.*:fa-bolt, \
+                        run.*:fa-bolt
+----
+
+where the key is a regex matching action names (eg `create.*`) and the value is a link:http://fortawesome.github.io/Font-Awesome/icons/[font-awesome] icon name (eg `fa-plus`) to be applied (as per `@CssClassFa()`) to all action members matching the regex.
+
+
+Similarly, the xref:../rgcfg/rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.reflector.facet.cssClass.patterns` is a comma separated list of key:value pairs, eg:
+
+[source,ini]
+----
+isis.reflector.facet.cssClass.patterns=\
+                        delete.*:btn-warning
+----
+
+where (again)the key is a regex matching action names (eg `delete.*`) and the value is a link:http://getbootstrap.com/css/[Bootstrap] CSS button class (eg `btn-warning) to be applied (as per `@CssClass()`) to all action members matching the regex.
+
+[TIP]
+====
+We strongly recommend that you use this technique rather than annotating each action with xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClassFa[`@ActionLayout#cssClassFa()`] or xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout#cssClass()`].  Not only is the code more maintainable, you'll also find that it forces you to be consistent in your action names.
+====
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_eager-rendering.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_eager-rendering.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_eager-rendering.adoc
new file mode 100644
index 0000000..212736a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_eager-rendering.adoc
@@ -0,0 +1,58 @@
+[[_ugfun_ui-hints_eager-rendering]]
+= Eager rendering
+: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/
+
+
+By default, collections all rendered lazily, in other words in a "collapsed" table view:
+
+NOTE: FIXME - screenshot here
+
+For the more commonly used collections we want to show the table expanded:
+
+NOTE: FIXME - screenshot here
+
+For this we annotate the collection using the `@CollectionLayout(render=RenderType.EAGERLY`; for example
+
+[source,java]
+----
+@javax.jdo.annotations.Persistent(table="ToDoItemDependencies")
+private Set<ToDoItem> dependencies = new TreeSet<>();
+@Collection
+@CollectionLayout(
+    render = RenderType.EAGERLY
+)
+public Set<ToDoItem> getDependencies() {
+    return dependencies;
+}
+----
+
+Alternatively, it can be specified the `Xxx.layout.json` file:
+
+[source,javascript]
+----
+"dependencies": {
+    "collectionLayout": {
+        "render": "EAGERLY"
+    },
+}
+----
+
+[WARNING]
+====
+It might be thought that collections that are eagerly rendered should also be eagerly loaded from the database by enabling the `defaultFetchGroup` attribute:
+
+[source,java]
+----
+@javax.jdo.annotations.Persistent(table="ToDoItemDependencies", defaultFetchGroup="true")
+private Set<ToDoItem> dependencies = new TreeSet<>();
+...
+----
+
+While this can be done, it's likely to be a bad idea, because doing so will cause DataNucleus to query for more data than required even if the object is being rendered within some referencing object's table.
+
+Of course, your mileage may vary, so don't think you can't experiment.
+====
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_layout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_layout.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_layout.adoc
new file mode 100644
index 0000000..eed9488
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_layout.adoc
@@ -0,0 +1,14 @@
+[[_ugfun_ui-hints_layout]]
+= Layout
+: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/
+
+
+The most significant aspect of the UI is the layout of the object's members: its properties, collections and actions.
+These can be organized into columns, rows and tabs.
+
+This can be accomplished using either annotations or through a separate file-based layout.
+Since this is a large topic, it has its own xref:../ugvw/ugvw.adoc#_ugvw_layout[layout chapter] in the Wicket viewer guide.
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_names-and-descriptions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_names-and-descriptions.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_names-and-descriptions.adoc
new file mode 100644
index 0000000..769ee79
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_names-and-descriptions.adoc
@@ -0,0 +1,47 @@
+[[_ugfun_ui-hints_names-and-descriptions]]
+= Names and Descriptions
+: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/
+
+NOTE: FIXME
+
+
+
+NOTE: see also xref:../ugbtb/ugbtb.adoc#_ugbtb_i18n[Internationalization]
+
+== Class (object)
+
+NOTE: FIXME - xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_named[`@DomainObjectLayout#named()`], xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_describedAs[`@DomainObjectLayout#describedAs()`]
+
+
+== Property
+
+NOTE: FIXME - xref:../rgant/rgant.adoc#_rgant-PropertyLayout_named[`@PropertyLayout#named()`], xref:../rgant/rgant.adoc#_rgant-PropertyLayout_describedAs[`@PropertyLayout#describedAs()`]
+
+
+
+== Collections
+
+NOTE: FIXME - xref:../rgant/rgant.adoc#_rgant-CollectionLayout_named[`@CollectionLayout#named()`], xref:../rgant/rgant.adoc#_rgant-CollectionLayout_describedAs[`@CollectionLayout#describedAs()`]
+
+
+
+== Actions
+
+NOTE: FIXME - xref:../rgant/rgant.adoc#_rgant-ActionLayout_named[`@ActionLayout#named()`], xref:../rgant/rgant.adoc#_rgant-ActionLayout_describedAs[`@ActionLayout#describedAs()`]
+
+
+== Action Parameters
+
+NOTE: FIXME - xref:../rgant/rgant.adoc#_rgant-ParameterLayout_named[`@ParameterLayout#named()`], xref:../rgant/rgant.adoc#_rgant-ParameterLayout_describedAs[`@ParameterLayout#describedAs()`]
+
+
+[TIP]
+====
+If you're running on Java 8, then note that it's possible to write Isis applications without using `@ParameterLayout(named=...)` annotation.  Support for this can be found in the link:http://github.com/isisaddons/isis-metamodel-paraname8[Isis addons' paraname8] metamodel extension (non-ASF).  (In the future we'll fold this into core).  See also our guidance on xref:release-notes.adoc#_migration-notes_1.8.0-to-1.9.0_upgrading-to-java8[upgrading to Java 8].
+====
+
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_object-titles-and-icons.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_object-titles-and-icons.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_object-titles-and-icons.adoc
new file mode 100644
index 0000000..1c8663a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_object-titles-and-icons.adoc
@@ -0,0 +1,97 @@
+[[_ugfun_ui-hints_object-titles-and-icons]]
+= Object Titles and Icons
+: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/
+
+
+In Apache Isis every object is identified to the user by a title (label) and an icon.  This is shown in several places: as the main heading for an object; as a link text for an object referencing another object, and also in tables representing collections of objects.
+
+The icon is often the same for all instances of a particular class, but it's also possible for an individual instance to return a custom icon.  This could represent the state of that object (eg a shipped order, say, or overdue library book).
+
+It is also possible for an object to provide a CSS class hint.  In conjunction with xref:../ugvw/ugvw.adoc#_ugvw_customisation_tweaking-css-classes[customized CSS] this can be used to apply arbitrary styling; for example each object could be rendered in a page with a different background colour.
+
+
+== Object Title
+
+The object title is a label to identify an object to the end-user.  Generally the object title is a label to identify an object to the end-user.  There is no requirement for it to be absolutely unique, but it should be "unique enough" to distinguish the object from other object's likely to be rendered on the same page.
+
+The title is always shown with an icon, so there is generally no need for the title to include information about the object's type.  For example the title of a customer object shouldn't include the literal string "Customer"; it can just have the customer's name, reference or some other meaningful business identifier.
+
+
+=== Declarative style
+
+The xref:../rgant/rgant.adoc#_rgant-Title[`@Title`] annotation can be used build up the title of an object from its constituent parts.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+    @Title(sequence="1", append=" ")
+    public String getFirstName() { ... }
+    @Title(sequence="2")
+    public Product getLastName() { ... }
+    ...
+}
+----
+
+might return "Arthur Clarke", while:
+
+[source,java]
+----
+public class CustomerAlt {
+    @Title(sequence="2", prepend=", ")
+    public String getFirstName() { ... }
+
+    @Title(sequence="1")
+    public Product getLastName() { ... }
+    ...
+}
+----
+
+could return "Clarke, Arthur".
+
+Note that the sequence is in Dewey Decimal Format.  This allows a subclass to intersperse information within the title.  For example (please forgive this horrible domain modelling (!)):
+
+
+[source,java]
+----
+public class Author extends Customer {
+    @Title(sequence="1.5", append=". ")
+    public String getMiddleInitial() { ... }
+    ...
+}
+----
+
+could return "Arthur C. Clarke".
+
+
+[TIP]
+====
+Titles can sometimes get be long and therefore rather cumbersome in "parented" tables.  If `@Title` has been used then the Wicket viewer will automatically exclude portions of the title belonging to the owning object.
+====
+
+
+=== Imperative style
+
+NOTE: FIXME - see xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_title[`title()`]
+
+
+
+
+== Object Icon
+
+The icon is often the same for all instances of a particular class, but it's also possible for an individual instance to return a custom icon.  This could represent the state of that object (eg a shipped order, say, or overdue library book).
+
+NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`], xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_cssClassFa[`@DomainObjectLayout#cssClassFa()`]
+
+
+
+
+== Object CSS Styling
+
+
+It is also possible for an object to return a xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_cssClass[CSS class].  In conjunction with xref:../ugvw/ugvw.adoc#_ugvw_customisation_tweaking-css-classes[customized CSS] this can be used to apply arbitrary styling; for example each object could be rendered in a page with a different background colour.
+
+NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_cssClass[`cssClass()`], xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_cssClass[`@DomainObjectLayout#cssClass()`] xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout#cssClass()`], xref:../rgant/rgant.adoc#_rgant-PropertyLayout_cssClass[`@PropertyLayout#cssClass()`], xref:../rgant/rgant.adoc#_rgant-CollectionLayout_cssClass[`@CollectionLayout#cssClass()`]

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugfun/ugfun.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/ugfun.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/ugfun.adoc
index e838c6e..432c473 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/ugfun.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/ugfun.adoc
@@ -49,8 +49,14 @@ The remaining guides are:
 include::_ugfun_core-concepts.adoc[leveloffset=+1]
 include::_ugfun_getting-started.adoc[leveloffset=+1]
 
-include::_ugfun_how-tos.adoc[leveloffset=+1]
-include::_ugvw_layout.adoc[leveloffset=+1]
+include::_ugfun_domain-class-ontology.adoc[leveloffset=+1]
 
-include::_ugfun_faqs.adoc[leveloffset=+1]
+include::_ugfun_class-structure.adoc[leveloffset=+1]
+include::_ugfun_ui-hints.adoc[leveloffset=+1]
+
+include::_ugfun_crud.adoc[leveloffset=+1]
+
+include::_ugfun_business-rules.adoc[leveloffset=+1]
+
+include::_ugfun_drop-downs-and-defaults.adoc[leveloffset=+1]
 

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/guides/ugvw/ugvw.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/ugvw.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/ugvw.adoc
index fde7dbc..4ecfe19 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/ugvw.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/ugvw.adoc
@@ -50,8 +50,8 @@ The remaining guides are:
 
 
 include::_ugvw_features.adoc[leveloffset=+1]
-include::_ugvw_configuration-properties.adoc[leveloffset=+1]
 include::_ugvw_layout.adoc[leveloffset=+1]
+include::_ugvw_configuration-properties.adoc[leveloffset=+1]
 include::_ugvw_customisation.adoc[leveloffset=+1]
 include::_ugvw_extending.adoc[leveloffset=+1]
 include::_ugvw_hints-and-tips.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/pages/screencasts/screencasts.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/pages/screencasts/screencasts.adoc b/adocs/documentation/src/main/asciidoc/pages/screencasts/screencasts.adoc
index 7a70d8e..ddcb3c8 100644
--- a/adocs/documentation/src/main/asciidoc/pages/screencasts/screencasts.adoc
+++ b/adocs/documentation/src/main/asciidoc/pages/screencasts/screencasts.adoc
@@ -87,7 +87,7 @@ Using xref:guides/ugtst.adoc#_ugtst_fixture-scripts[fixture scripts] to initiali
 
 
 |link:https://www.youtube.com/watch?v=dXtmxmYxa30[006^] +
-Implementing xref:guides/ugfun.adoc#_ugfun_how-tos_business-rules[business rules]for domain object members, using supporting methods ("see it, use it, do it")
+Implementing xref:guides/ugfun.adoc#_ugfun_business-rules[business rules]for domain object members, using supporting methods ("see it, use it, do it")
 |x||||||||||
 
 |link:https://www.youtube.com/watch?v=imHfxQGUgV8[007^] +

http://git-wip-us.apache.org/repos/asf/isis/blob/480d6ff2/adocs/documentation/src/main/asciidoc/pages/tg/_tg_stop-scaffolding-start-coding.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/pages/tg/_tg_stop-scaffolding-start-coding.adoc b/adocs/documentation/src/main/asciidoc/pages/tg/_tg_stop-scaffolding-start-coding.adoc
index f8dcbb1..ed75f22 100644
--- a/adocs/documentation/src/main/asciidoc/pages/tg/_tg_stop-scaffolding-start-coding.adoc
+++ b/adocs/documentation/src/main/asciidoc/pages/tg/_tg_stop-scaffolding-start-coding.adoc
@@ -206,8 +206,8 @@ Most domain objects in Apache Isis applications are persistent entities. In the
 ** eg rename to `Pet`
 * if required, rename the `SimpleObject` class' `name` property
 ** for `Pet`, can leave `name` property as is
-* specify a xref:../../guides/ugfun/ugfun.adoc#_ugfun_how-tos_ui-hints_object-titles-and-icons[title]
-* specify an xref:../../guides/ugfun/ugfun.adoc#_ugfun_how-tos_ui-hints_object-titles-and-icons[icon]
+* specify a xref:../../guides/ugfun/ugfun.adoc#_ugfun_ui-hints_object-titles-and-icons[title]
+* specify an xref:../../guides/ugfun/ugfun.adoc#_ugfun_ui-hints_object-titles-and-icons[icon]
 * make the entity bookmarkable by adding the xref:../../guides/rgant/rgant.adoc#_rgant-DomainObjectLayout_bookmarking[`@DomainObjectLayout#bookmarking()`] attribute.
 * confirm is available from bookmark panel (top-left of Wicket UI)
 
@@ -223,11 +223,11 @@ In the simpleapp archetype the `SimpleObjects` service is a factory/repository f
 * rename the `SimpleObjects` class
 ** eg rename to `Pets`
 * review `create` action (acting as a factory)
-** as per the docs describing xref:../../guides/ugfun/ugfun.adoc#_ugfun_how-tos_crud[how to create or delete objects]
+** as per the docs describing xref:../../guides/ugfun/ugfun.adoc#_ugfun_crud[how to create or delete objects]
 * rename if you wish
 ** eg `newPet(...)` or `addPet(...)`
 * review `listAll` action (acting as a repository)
-* as per the docs describing xref:../../guides/ugfun/ugfun.adoc#_ugfun_how-tos_crud[how to write a custom repository]
+* as per the docs describing xref:../../guides/ugfun/ugfun.adoc#_ugfun_crud[how to write a custom repository]
 * note the annotations on the corresponding domain class (originally called `SimpleObject`, though renamed by now, eg to `Pet`)
 * rename if you wish
 ** eg `listPets()`
@@ -300,7 +300,7 @@ The semantics of an action (whether it is safe/query only, whether it is idempot
 
 Domain entities have state: either values (primitives, strings) or references to other entities. In this section we explore adding some value properties
 
-* add some xref:../../guides/ugfun/ugfun.adoc#_ugfun_how-tos_class-structure_properties[value properties]; also:
+* add some xref:../../guides/ugfun/ugfun.adoc#_ugfun_class-structure_properties[value properties]; also:
 * for string properties
 ** use the xref:../../guides/rgant/rgant.adoc#_rgant-PropertyLayout_multiLine[`@PropertyLayout(multiLine=...)`] annotation to render a text area instead of a text box
 ** use the xref:../../guides/rgant/rgant.adoc#_rgant-Property_maxLength[`@Property(maxLength=...)`] annotation to specify the maximum number of characters allowable
@@ -324,7 +324,7 @@ Domain entities have state: either values (primitives, strings) or references to
 
 Domain entities can also reference other domain entities. These references may be either scalar (single-valued) or vector (multi-valued). In this section we focus on scalar reference properties.
 
-* add some xref:../../guides/ugfun/ugfun.adoc#_ugfun_how-tos_class-structure_properties[reference properties]
+* add some xref:../../guides/ugfun/ugfun.adoc#_ugfun_class-structure_properties[reference properties]
 * update the corresponding domain service (for creation actoin)
 * use different techniques to obtain references (shown in drop-down list box)
 ** use the xref:../../guides/rgant/rgant.adoc#_rgant-DomainObject_bounded[`@DomainObjectLayout(bounded=...)`] annotation on the referenced type if there are only a small number (bounded) of instances
@@ -342,7 +342,7 @@ Domain entities can also reference other domain entities. These references may b
 
 Quick detour: often we want to set up defaults to go with choices. Sensible defaults for action parameters can really improve the usability of the app.
 
-* Add xref:../../guides/ugfun/ugfun.adoc#_ugfun_how-tos_drop-downs-and-defaults[defaults] for action parameters
+* Add xref:../../guides/ugfun/ugfun.adoc#_ugfun_drop-downs-and-defaults[defaults] for action parameters
 
 
 
@@ -354,7 +354,7 @@ Returning back to references, Isis also supports vector (multi-valued) reference
 * Ensure that all domain classes implement `java.lang.Comparable`
 ** use the xref:../../guides/rgcms/rgcms.adoc#_rgcms_classes_utility_ObjectContracts[`ObjectContracts`] utility class to help implement `Comparable`
 *** you can also implement `equals()`, `hashCode()`, `toString()`
-* Add a xref:../../guides/ugfun/ugfun.adoc#_ugfun_how-tos_class-structure_collections[collection] to one of the entities
+* Add a xref:../../guides/ugfun/ugfun.adoc#_ugfun_class-structure_collections[collection] to one of the entities
 ** Use `SortedSet` as the class
 ** Use the xref:../../guides/rgant/rgant.adoc#_rgant-CollectionLayout_render[`@CollectionLayout(render=...)`] annotation to indicate if the collection should be visible or hidden by default
 * optional: use the xref:../../guides/rgant/rgant.adoc#_rgant-CollectionLayout_sortedBy[`@CollectionLayout(sortedBy=...)`] annotation to specify a different comparator than the natural ordering
@@ -368,7 +368,7 @@ Returning back to references, Isis also supports vector (multi-valued) reference
 The Wicket UI doesn't allow collections to be modified (added to/removed from). However, we can easily write actions to accomplish the same. Moreover, these actions can provide some additional business logic. For example: it probably shouldn't be possible to add an object twice into a collection, so it should not be presented in the list of choices/autoComplete; conversely, only those objects in the collection should be offered as choices to be removed.
 
 * Add domain actions to add/remove from the collection
-* to create objects, xref:../../guides/ugfun/ugfun.adoc#_ugfun_how-tos_class-structure_inject-services[inject] associated domain service
+* to create objects, xref:../../guides/ugfun/ugfun.adoc#_ugfun_class-structure_inject-services[inject] associated domain service
 ** generally we recommend using the xref:../../guides/rgant/rgant.adoc#_rgant-Inject[`@Inject`] annotation with either private or default visibility
 * the service itself should use xref:../../guides/rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`]
 * use the xref:../../guides/rgant/rgant.adoc#_rgant-MemberOrder[`@MemberOrder(name=...)`] annotation to associate an action with a property or with a collection
@@ -384,7 +384,7 @@ CSS classes can be associated with any class member (property, collection, actio
 
 *  the http://fortawesome.github.io/Font-Awesome/icons/[Font Awesome] icons can be used using the xref:../../guides/rgant/rgant.adoc#_rgant-ActionLayout_cssClassFa[`@ActionLayout(cssClassFa=...)`]
 
-It's also possible to use Font Awesome icons for the xref:../../guides/ugfun/ugfun.adoc#_ugfun_how-tos_ui-hints_object-titles-and-icons[domain object icon].
+It's also possible to use Font Awesome icons for the xref:../../guides/ugfun/ugfun.adoc#_ugfun_ui-hints_object-titles-and-icons[domain object icon].
 
 So:
 - for some of the actions of your domain services or entities, annotate using `@ActionLayout(cssClass=...)` or `@ActionLayout(cssClassFa=...)`

[03/58] [abbrv] isis git commit: ISIS-1521: fixes xref links between guides

[da...@apache.org]

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_web-xml.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_web-xml.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_web-xml.adoc
index b81637b..8f03333 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_web-xml.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_web-xml.adoc
@@ -378,7 +378,7 @@ This filter reads one context parameter:
     <param-value>deployment</param-value>   <!--1-->
 </context-param>
 ----
-<1> alternatively set to "development"; see xref:rgcfg.adoc#_rgcfg_deployment-types[deployment types] for further discussion.
+<1> alternatively set to "development"; see xref:../rgcfg/rgcfg.adoc#_rgcfg_deployment-types[deployment types] for further discussion.
 
 
 === `IsisSessionFilter`

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_cqrs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_cqrs.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_cqrs.adoc
index ea526e0..37eb157 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_cqrs.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_cqrs.adoc
@@ -31,10 +31,10 @@ There are other reasons though why a separate read model might make sense, such
 In these cases Apache Isis can often provide a reasonable alternative, namely to map domain entities against RDBMS views, either materialized views or dynamic.
 In such cases there is still only a single physical datastore, and so transactional integrity is retained.
 
-Or, the CQRS architecture can be more fully implemented with Apache Isis by introducing a separate read model, synchronized using the xref:rgsvc.adoc#_rgsvc_api_PublishingService[`PublishingService`], or using xref:rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscribers]  on the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`].
+Or, the CQRS architecture can be more fully implemented with Apache Isis by introducing a separate read model, synchronized using the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_PublishingService[`PublishingService`], or using xref:../rgcms/rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscribers]  on the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`].
 One can then use xref:ugbtb.adoc#_ugbtb_view-models[view models] to surface the data in the external read datastore.
 
-With respect to commands, Apache Isis does of course support the xref:rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] which allows each business action to be reified into a `Command`.
+With respect to commands, Apache Isis does of course support the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] which allows each business action to be reified into a `Command`.
 However, names are misleading here: Apache Isis' commands are relatively passive, merely recording the intent of the user to invoke some operation.
 In a CQRS architecture, though, commands take a more active role, locating and acting upon the domain objects.
 More significantly, in CQRS each command has its own class, such as `PlaceOrderCommand`, instantiated by the client and then executed.
@@ -43,7 +43,7 @@ With Apache Isis, though, the end-user merely invokes the `placeOrder(...)` acti
 In CQRS the commands correspond to the business logic that mutates the system.
 Whether this logic is part of the command class (`PlaceOrderCommand`) or whether that command delegates to methods on the domain object is an implementation detail; but it certainly is common for the business logic to be wholly within the command object and for the domain object to be merely a data holder of the data within the command/write datastore.
 
-In Apache Isis this same separation of business logic from the underlying data can be accomplished most straightforwardly using xref:ugbtb.adoc#_ugbtb_decoupling_mixins[mixins] or xref:ugfun.adoc#_ugfun_how-tos_contributed-members[contributions].
+In Apache Isis this same separation of business logic from the underlying data can be accomplished most straightforwardly using xref:ugbtb.adoc#_ugbtb_decoupling_mixins[mixins] or xref:../ugfun/ugfun.adoc#_ugfun_how-tos_contributed-members[contributions].
 In the UI (surfaced by the xref:ugvw.adoc#[Wicket viewer]) or in the REST API (surfaced by the xref:ugvro.adoc#[RestfulObjects viewer]) the behaviour appears to reside on the domain object; however the behaviour actually resides on separate classes and is mixed in (like a trait) only at runtime.
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_event-sourcing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_event-sourcing.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_event-sourcing.adoc
index 4b7fd58..2fa5a7f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_event-sourcing.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_event-sourcing.adoc
@@ -22,8 +22,8 @@ Note that the event might be dispatched and consumed in-process or alternatively
 If the latter, then the subscriber will operate within a separate transaction, meaning the usual eventual consistency concerns and also compensating actions if a rollback is required.
 CQRS/event sourcing advocates point out -- correctly -- that this is just how things are in the "real world" too.
 
-In Apache Isis every business action (and indeed, property and collection) emits domain events through the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`], and can optionally also be published through the xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`].
-The former are dispatched and consumed in-process and within the same transaction, and for this reason the xref:rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscribers] can also veto the events.
+In Apache Isis every business action (and indeed, property and collection) emits domain events through the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`], and can optionally also be published through the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`].
+The former are dispatched and consumed in-process and within the same transaction, and for this reason the xref:../rgcms/rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscribers] can also veto the events.
 The latter are intended for out-of-process consumption; the (non-ASF) http://github.com/isisaddons/isis-module-publishing[Isis addons' publishing] and http://github.com/isisaddons/isis-module-publishmq[Isis addons' publishmq] modules provide implementations for dispatching either through a RDBMS database table, or directly through to an link:http://camel.apache.org[ActiveMQ] message queue (eg wired up to link:http://camel.apache.org[Apache Camel] event bus).
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_metawidget.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_metawidget.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_metawidget.adoc
index 02fa963..22c1cf4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_metawidget.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_metawidget.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-MetaWidget (mentioned xref:ugfun.adoc#_ugfun_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping[earlier] has a number of ideas in common with Apache Isis, specifically the runtime generation of a UI for domain objects.
+MetaWidget (mentioned xref:../ugfun/ugfun.adoc#_ugfun_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping[earlier] has a number of ideas in common with Apache Isis, specifically the runtime generation of a UI for domain objects.
 And like Apache Isis, MetaWidget builds its own metamodel of the domain objects and uses this to render the object.
 
 However, there is a difference in philosophy in that MW is not a full-stack framework and does not (in their words) try to "own the UI".

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_building-blocks.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_building-blocks.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_building-blocks.adoc
index 95a889c..950f175 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_building-blocks.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_building-blocks.adoc
@@ -65,7 +65,7 @@ Another variation are *contributed services*: domain services that contribute be
 Finally domain services may also simply provide additional non-UI functionality; an example being to perform an address geocoding lookup against the google-maps API.
 
 Also worth mentioning: domain services can also be either singletons (discussed above) or request-scoped; the latter being annotated with `@javax.enterprise.context.RequestScoped`.
-An example of the request-scoped service is the xref:rgsvc.adoc#_rgsvc_api_Scratchpad[`Scratchpad`] service, for sharing arbitrary data between multiple objects.
+An example of the request-scoped service is the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_Scratchpad[`Scratchpad`] service, for sharing arbitrary data between multiple objects.
 
 The final type of domain object is the *mixin*.
 These are similar to contributed services in that they also contribute (or rather, mixin) both behaviour or (derived) state to entities/view models.
@@ -251,13 +251,13 @@ For more information, see xref:ugbtb.adoc#_ugbtb_decoupling_contributions[this t
 [[__ugfun_core-concepts_building-blocks_domain-events]]
 == Domain Events
 
-NOTE: FIXME; see xref:rgcms.adoc#_rgcms_classes_domainevent[domain event] classes.
+NOTE: FIXME; see xref:../rgcms/rgcms.adoc#_rgcms_classes_domainevent[domain event] classes.
 
 
 
 === UI Events
 
-NOTE: FIXME; see xref:rgcms.adoc#_rgcms_classes_uievent[UI event] classes.
+NOTE: FIXME; see xref:../rgcms/rgcms.adoc#_rgcms_classes_uievent[UI event] classes.
 
 
 
@@ -265,7 +265,7 @@ NOTE: FIXME; see xref:rgcms.adoc#_rgcms_classes_uievent[UI event] classes.
 [[__ugfun_core-concepts_building-blocks_oid]]
 == OIDs
 
-As well as defining a xref:ugfun.adoc#__ugfun_core-concepts_building-blocks_metamodel[metamodel] of the structure (domain classes) of its domain objects, Apache Isis also manages the runtime instances of said domain objects.
+As well as defining a xref:../ugfun/ugfun.adoc#__ugfun_core-concepts_building-blocks_metamodel[metamodel] of the structure (domain classes) of its domain objects, Apache Isis also manages the runtime instances of said domain objects.
 
 When a domain entity is recreated from the database, the framework keeps track of its identity through an "OID": an object identifier.
 Fundamentally this is a combination of its type (domain class), along with an identifier.
@@ -285,12 +285,12 @@ Some examples:
 * the information within an OID could be converted into a barcode, and stamped onto a PDF form.
 When the PDF is scanned by the mail room, the barcode could be read to attach the correspondence to the relevant domain object.
 
-* as a handle to any object in an audit record, as used by xref:rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditerService`] or xref:rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`] (the latter deprecated);
+* as a handle to any object in an audit record, as used by xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditerService`] or xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`] (the latter deprecated);
 
-* similarly within implementations of xref:rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] to persist `Command`
+* similarly within implementations of xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] to persist `Command`
 objects
 
-* similarly within implementations of xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`]
+* similarly within implementations of xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`]
 to persist published action invocations
 
 * and of course both the xref:ugvro.adoc#[RestfulObjects viewer] and
@@ -298,11 +298,11 @@ xref:ugvw.adoc#[Wicket viewer]
 use the oid tuple to look up, render and allow the user to interact with domain objects.
 
 Although the exact content of an OID should be considered opaque by domain objects, it is possible for domain objects to obtain OIDs.
-These are represented as `Bookmark`s, obtained from the xref:rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`].
-Deep links meanwhile can be obtained from the xref:rgant.adoc#_rgant-DeepLinkService[`@DeepLinkService`].
+These are represented as `Bookmark`s, obtained from the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`].
+Deep links meanwhile can be obtained from the xref:../rgant/rgant.adoc#_rgant-DeepLinkService[`@DeepLinkService`].
 
 OIDs can also be converted into XML format, useful for integration scenarios.
-The xref:rgcms.adoc#_rgcms_schema-common[common schema] XSD defines the `oidDto` complex type for precisely this purpose.
+The xref:../rgcms/rgcms.adoc#_rgcms_schema-common[common schema] XSD defines the `oidDto` complex type for precisely this purpose.
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_framework-provided-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_framework-provided-services.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_framework-provided-services.adoc
index f4558b8..3eeaac0 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_framework-provided-services.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_framework-provided-services.adoc
@@ -14,94 +14,94 @@ In these cases there is (usually) no default implementation; it is up to the app
 
 General purpose:
 
-* xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`]; mostly deprecated, replaced by:
-** xref:rgsvc.adoc#_rgsvc_api_ClockService[`ClockService`]
-** xref:rgsvc.adoc#_rgsvc_api_ConfigurationService[`ConfigurationService`]
-** xref:rgsvc.adoc#_rgsvc_api_MessageService[`MessageService`]
-** xref:rgsvc.adoc#_rgsvc_api_RepositoryService[`RepositoryService`]
-** xref:rgsvc.adoc#_rgsvc_api_ServiceRegistry[`ServiceRegistry`]
-** xref:rgsvc.adoc#_rgsvc_api_TitleService[`TitleService`]
-** xref:rgsvc.adoc#_rgsvc_api_UserService[`UserService`]
-* xref:rgsvc.adoc#_rgsvc_api_IsisJdoSupport[`IsisJdoSupport`]
-* xref:rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`]
-* xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`]
-* xref:rgsvc.adoc#_rgsvc_api_EmailService[`EmailService`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`]; mostly deprecated, replaced by:
+** xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ClockService[`ClockService`]
+** xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ConfigurationService[`ConfigurationService`]
+** xref:../rgsvc/rgsvc.adoc#_rgsvc_api_MessageService[`MessageService`]
+** xref:../rgsvc/rgsvc.adoc#_rgsvc_api_RepositoryService[`RepositoryService`]
+** xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ServiceRegistry[`ServiceRegistry`]
+** xref:../rgsvc/rgsvc.adoc#_rgsvc_api_TitleService[`TitleService`]
+** xref:../rgsvc/rgsvc.adoc#_rgsvc_api_UserService[`UserService`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_IsisJdoSupport[`IsisJdoSupport`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EmailService[`EmailService`]
 
 Commands/Interactions/Background/Auditing/Publishing/Profiling:
 
-* xref:rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`] (SPI)
-* xref:rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] (SPI)
-* xref:rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] (SPI)
-* xref:rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`] (SPI) (deprecated)
-* xref:rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditerService`] (SPI)
-* xref:rgsvc.adoc#_rgsvc_api_BackgroundService[`BackgroundService`]
-* xref:rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[`BackgroundCommandService`] (SPI)
-* xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`] (SPI) (deprecated)
-* xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublishererService`] (SPI)
-* xref:rgsvc.adoc#_rgsvc_api_MetricsService[`MetricsService`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`] (SPI) (deprecated)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditerService`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BackgroundService[`BackgroundService`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[`BackgroundCommandService`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`] (SPI) (deprecated)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublisherService[`PublishererService`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_MetricsService[`MetricsService`]
 
 
 Information Sharing:
 
-* xref:rgsvc.adoc#_rgsvc_api_Scratchpad[`Scratchpad`]
-* xref:rgsvc.adoc#_rgsvc_api_ActionInvocationContext[`ActionInvocationContext`]
-* xref:rgsvc.adoc#_rgsvc_api_QueryResultsCache[`QueryResultsCache`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_Scratchpad[`Scratchpad`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ActionInvocationContext[`ActionInvocationContext`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_QueryResultsCache[`QueryResultsCache`]
 
 UserManagement:
 
-* xref:rgsvc.adoc#_rgsvc_spi_UserProfileService[`UserProfileService`] (SPI)
-* xref:rgsvc.adoc#_rgsvc_spi_UserRegistrationService[`UserRegistrationService`] (SPI)
-* xref:rgsvc.adoc#_rgsvc_spi_EmailNotificationService[`EmailNotificationService`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UserProfileService[`UserProfileService`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UserRegistrationService[`UserRegistrationService`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_EmailNotificationService[`EmailNotificationService`] (SPI)
 
 Bookmarks and Mementos:
 
-* xref:rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`]
-* xref:rgsvc.adoc#_rgsvc_api_MementoService[`MementoService`]
-* xref:rgsvc.adoc#_rgsvc_api_DeepLinkService[`DeepLinkService`]
-* xref:rgsvc.adoc#_rgsvc_api_JaxbService[`JaxbService`]
-* xref:rgsvc.adoc#_rgsvc_api_XmlSnapshotService[`XmlSnapshotService`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_MementoService[`MementoService`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DeepLinkService[`DeepLinkService`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_JaxbService[`JaxbService`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_XmlSnapshotService[`XmlSnapshotService`]
 
 Layout and UI Management:
 
-* xref:rgsvc.adoc#_rgsvc_spi_GridLoaderService[`GridLoaderService`] (SPI)
-* xref:rgsvc.adoc#_rgsvc_spi_GridService[`GridService`] (SPI)
-* xref:rgsvc.adoc#_rgsvc_spi_GridSystemService[`GridSystemService`] (SPI)
-* xref:rgsvc.adoc#_rgsvc_api_HomePageProviderService[`HomePageProviderService`]
-* xref:rgsvc.adoc#_rgsvc_spi_HintStore[`HintStore`] (SPI)
-* xref:rgsvc.adoc#_rgsvc_api_LayoutService[`LayoutService`]
-* xref:rgsvc.adoc#_rgsvc_spi_RoutingService[`RoutingService`] (SPI)
-* xref:rgsvc.adoc#_rgsvc_spi_UrlEncodingService[`UrlEncodingService`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_GridLoaderService[`GridLoaderService`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_GridService[`GridService`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_GridSystemService[`GridSystemService`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_HomePageProviderService[`HomePageProviderService`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_HintStore[`HintStore`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_LayoutService[`LayoutService`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_RoutingService[`RoutingService`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UrlEncodingService[`UrlEncodingService`] (SPI)
 
 REST Support:
 
-* xref:rgsvc.adoc#_rgsvc_api_AcceptHeaderService[`AcceptHeaderService`]
-* xref:rgsvc.adoc#_rgsvc_api_SwaggerService[`SwaggerService`]
-* xref:rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_AcceptHeaderService[`AcceptHeaderService`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_SwaggerService[`SwaggerService`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`] (SPI)
 
 Metamodel:
 
-* xref:rgsvc.adoc#_rgsvc_api_ApplicationFeatureRepository[`ApplicationFeatureRepository`]
-* xref:rgsvc.adoc#_rgsvc_api_MetamodelService[`MetamodelService`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ApplicationFeatureRepository[`ApplicationFeatureRepository`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_MetamodelService[`MetamodelService`]
 
 Other API:
 
-* xref:rgsvc.adoc#_rgsvc_api_FixtureScriptsDefault[`FixtureScriptsDefault`]
-* xref:rgsvc.adoc#_rgsvc_api_GuiceBeanProvider[`GuiceBeanProvider`]
-* xref:rgsvc.adoc#_rgsvc_api_SudoService[`SudoService`]
-* xref:rgsvc.adoc#_rgsvc_api_TransactionService[`TransactionService`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_FixtureScriptsDefault[`FixtureScriptsDefault`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_GuiceBeanProvider[`GuiceBeanProvider`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_SudoService[`SudoService`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_TransactionService[`TransactionService`]
 
 Other SPI:
 
-* xref:rgsvc.adoc#_rgsvc_spi_ClassDiscoveryService[`ClassDiscoveryService`] (SPI)
-* xref:rgsvc.adoc#_rgsvc_spi_ErrorReportingService[`ErrorReportingService`] (SPI)
-* xref:rgsvc.adoc#_rgsvc_spi_EventSerializer[`EventSerializer`] (SPI)
-* xref:rgsvc.adoc#_rgsvc_spi_ExceptionRecognizer[`ExceptionRecognizer`] (SPI)
-* xref:rgsvc.adoc#_rgsvc_spi_FixtureScriptsSpecificationProvider[`FixtureScriptsSpecificationProvider`] (SPI)
-* xref:rgsvc.adoc#_rgsvc_spi_LocaleProvider[`LocaleProvider`] (SPI)
-* xref:rgsvc.adoc#_rgsvc_spi_TranslationService[`TranslationService`] (SPI)
-* xref:rgsvc.adoc#_rgsvc_spi_TranslationsResolver[`TranslationsResolver`] (SPI)
-* xref:rgsvc.adoc#_rgsvc_spi_TranslationsResolver[`TranslationsResolver`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ClassDiscoveryService[`ClassDiscoveryService`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ErrorReportingService[`ErrorReportingService`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_EventSerializer[`EventSerializer`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ExceptionRecognizer[`ExceptionRecognizer`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_FixtureScriptsSpecificationProvider[`FixtureScriptsSpecificationProvider`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_LocaleProvider[`LocaleProvider`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_TranslationService[`TranslationService`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_TranslationsResolver[`TranslationsResolver`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_TranslationsResolver[`TranslationsResolver`] (SPI)
 
 
-A full list of services can be found in the xref:rgsvc.adoc#_rgsvc[Domain Services] reference guide.
+A full list of services can be found in the xref:../rgsvc/rgsvc.adoc#_rgsvc[Domain Services] reference guide.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_other-deployment-options.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_other-deployment-options.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_other-deployment-options.adoc
index 3aef8d4..b38c55c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_other-deployment-options.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_other-deployment-options.adoc
@@ -18,7 +18,7 @@ Let's start though with the default use case for Apache Isis: building line-of-b
 
 Apache Wicket, and therefore Apache Isis in this configuration, is a stateful architecture.  As a platform it is certainly capable of supporting user bases of several thousand (with perhaps one or two hundred concurrent); however it isn't an architecture that you should try to scale up to tens of thousands of concurrent users.
 
-The UI UI generated by the Wicket viewer is well suited to many line-of-business apps, but it's also worth knowing that (with a little knowledge of the Wicket APIs) it relatively straightforward to extend.  As described in xref:ugfun.adoc#_ugfun_core-concepts_add-ons[Isis addons] chapter, the viewer already has integrations with https://github.com/isisaddons/isis-wicket-gmap3[google maps], https://github.com/isisaddons/isis-wicket-fullcalendar2[a full calendar] and an https://github.com/isisaddons/isis-wicket-excel[export to Excel] component.  We are also aware of integrations with SVG images (for floor maps of shopping center) and of custom widgets displaying a catalogue (text and images) of medical diseases.
+The UI UI generated by the Wicket viewer is well suited to many line-of-business apps, but it's also worth knowing that (with a little knowledge of the Wicket APIs) it relatively straightforward to extend.  As described in xref:../ugfun/ugfun.adoc#_ugfun_core-concepts_add-ons[Isis addons] chapter, the viewer already has integrations with https://github.com/isisaddons/isis-wicket-gmap3[google maps], https://github.com/isisaddons/isis-wicket-fullcalendar2[a full calendar] and an https://github.com/isisaddons/isis-wicket-excel[export to Excel] component.  We are also aware of integrations with SVG images (for floor maps of shopping center) and of custom widgets displaying a catalogue (text and images) of medical diseases.
 
 Deploying on Apache Isis means that the framework also manages object persistence.  For many line-of-business applications this will mean using a relational database.  It is also possible (courtesy of its integratinon with link:http://www.datanucleus.org[DataNucleus]) to deploy an Isis app to a NoSQL store such as Neo4J or MongoDB; and it is also possible to deploy to cloud platforms such as link:https://cloud.google.com/appengine/docs[Google App Engine (GAE)].
 
@@ -41,7 +41,7 @@ Once you've sketched out your domain model, you can then "start-over" using your
 The programming model defined by Apache Isis deliberately minimizes the dependencies on the rest of the framework. In fact, the only hard dependency that the domain model classes have on Apache Isis is through the `org.apache.isis.applib` classes, mostly to pick up annotations such as `@Disabled`.
 So, if you have used Apache Isis for prototyping (discussed above), then note that it's quite feasible to take your domain model a the basis of your actual development effort; Apache Isis' annotations and programming conventions will help ensure that any subtle semantics you might have captured in your prototyping are not lost.
 
-If you go this route, your deployment platform will of course need to provide similar capabilities to Apache Isis.  In particular, you'll need to figure out a way to inject domain services into domain entities (eg using a JPA listener), and you'll also need to reimplement any domain services you have used that Apache Isis provides "out-of-the-box" (eg xref:rgsvc.adoc#_rgsvc_api_QueryResultsCache[`QueryResultsCache`] domain service).
+If you go this route, your deployment platform will of course need to provide similar capabilities to Apache Isis.  In particular, you'll need to figure out a way to inject domain services into domain entities (eg using a JPA listener), and you'll also need to reimplement any domain services you have used that Apache Isis provides "out-of-the-box" (eg xref:../rgsvc/rgsvc.adoc#_rgsvc_api_QueryResultsCache[`QueryResultsCache`] domain service).
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_aop.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_aop.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_aop.adoc
index db37fec..7a640ba 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_aop.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_aop.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-Although not a book about object modelling, Evans' "Domain Driven Design" does use object orientation as its primary modelling tool; while xref:ugfun.adoc#_ugfun_core-concepts_philosophy_naked-objects-pattern[naked objects pattern] very much comes from an OO background (it even has 'object' in its name).
+Although not a book about object modelling, Evans' "Domain Driven Design" does use object orientation as its primary modelling tool; while xref:../ugfun/ugfun.adoc#_ugfun_core-concepts_philosophy_naked-objects-pattern[naked objects pattern] very much comes from an OO background (it even has 'object' in its name).
 Richard Pawson -- the originator of Naked Objects pattern -- lists Alan Kay as a key influence.
 
 It's certainly true that to develop an Apache Isis application you will need to have good object oriented modelling skills.
@@ -55,7 +55,7 @@ Finally, Isis also a feature that is akin to AOP mix-ins.
 A "contributed action" is one that is implemented on a domain service but that appears to be a behaviour of rendered domain object.
 In other words, we can dissociate behaviour from data.
 That's not always the right thing to do of course.
-In Richard Pawson's description of the xref:ugfun.adoc#_ugfun_core-concepts_philosophy_naked-objects-pattern[naked objects pattern] he talks about "behaviourally rich" objects, in other words where the business functionality encapsulated the data.
+In Richard Pawson's description of the xref:../ugfun/ugfun.adoc#_ugfun_core-concepts_philosophy_naked-objects-pattern[naked objects pattern] he talks about "behaviourally rich" objects, in other words where the business functionality encapsulated the data.
 But on the other hand sometimes the behaviour and data structures change at different rates.
 The link:http://en.wikipedia.org/wiki/Single_responsibility_principle[single responsibility principle] says we should only lump code together that changes at the same rate.
 Apache Isis' support for contributions (not only contributed actions, but also contributed properties and contributed collections) enables this.

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_how-eases-ddd.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_how-eases-ddd.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_how-eases-ddd.adoc
index c5054e0..1ccf108 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_how-eases-ddd.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_how-eases-ddd.adoc
@@ -53,7 +53,7 @@ If we are using code as the primary means of expressing the model, then we need
 
 We could generate UML diagrams and the like from code. That will work for some members of the business community, but not for everyone. Or we could generate a PDF document from Javadoc comments, but comments aren't code and so the document may be inaccurate.  Anyway, even if we do create such a document, not everyone will read it.
 
-A better way to represent the model is to show it in action as a working prototype. As we show in the xref:ugfun.adoc#_ugfun_getting-started[Getting Started] section, Apache Isis enables this with ease. Such prototypes bring the domain model to life, engaging the audience in a way that a piece of paper never can.
+A better way to represent the model is to show it in action as a working prototype. As we show in the xref:../ugfun/ugfun.adoc#_ugfun_getting-started[Getting Started] section, Apache Isis enables this with ease. Such prototypes bring the domain model to life, engaging the audience in a way that a piece of paper never can.
 
 Moreover, with Apache Isis prototypes, the domain model will come shining through. If there are mistakes or misunderstandings in the domain model (inevitable when building any complex system), they will be obvious to all.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping.adoc
index 77c96f1..1a98d77 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping.adoc
@@ -11,5 +11,5 @@ We sometimes use this idea to explain naked objects to a bunch of developers.
 Just as an ORM (such as link:http://datanucleus.org[DataNucleus] or link:http://hibernate.org[Hibernate]) maps domain entities to a database, you can think of the naked objects pattern as representing the concept of mapping domain objects to a user interface.
 
 This is the way that the link:http://metawidget.org/[MetaWidget] team, in particular Richard Kennard, the primary contributor, likes to describe their tool.
-MetaWidget has a number of ideas in common with Apache Isis (we compare Apache Isis' with MetaWidget xref:ugfun.adoc#_ugfun_core-concepts_principles_apache-isis-vs_metawidget[here]), in particular the runtime generation of a UI for domain objects.
+MetaWidget has a number of ideas in common with Apache Isis (we compare Apache Isis' with MetaWidget xref:../ugfun/ugfun.adoc#_ugfun_core-concepts_principles_apache-isis-vs_metawidget[here]), in particular the runtime generation of a UI for domain objects.
 You can hear more from Kennard and others on this http://devchat.tv/js-jabber/150-jsj-oims[Javascript Jabber podcast].

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_for-the-long-term.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_for-the-long-term.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_for-the-long-term.adoc
index c53a18b..6fa5091 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_for-the-long-term.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_for-the-long-term.adoc
@@ -33,7 +33,7 @@ To support the business domain being split into separate modules, the framework
 
 * dependency injection of services +
 +
-Both xref:rgsvc.adoc#[framework-defined domain services] and application-defined services (eg repositories and factories) are injected everywhere, using the regular xref:rgant.adoc#_rgant-Inject[`@javax.inject.Inject`] annotation.
+Both xref:../rgsvc/rgsvc.adoc#[framework-defined domain services] and application-defined services (eg repositories and factories) are injected everywhere, using the regular xref:../rgant/rgant.adoc#_rgant-Inject[`@javax.inject.Inject`] annotation.
 
 * mixins allow functionality defined in one module to appear (in the UI) to be provided by some other module. +
 +
@@ -54,7 +54,7 @@ Or, it might conceivably perform a cascade delete of all associated communicatio
 
 For those cases where a module needs to interact with other modules but does not know about their implementations, the module can either define its own link:https://en.wikipedia.org/wiki/Service_provider_interface[SPI] domain services or it can define custom domain events and fire them.
 This technique is also used extensively by the framework itself.
- For example, the xref:rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditerService`] SPI enables custom auditing, and the xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] SPI enables custom publishing
+ For example, the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditerService`] SPI enables custom auditing, and the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] SPI enables custom publishing
 
 When building a modular application, it's important to consider the logical layering of the modules: we don't need every module to be completely decoupled from every other.
 The most important requirement is that there are no cyclic dependencies, because otherwise we run the risk of the application degrading into a link:https://en.wikipedia.org/wiki/Big_ball_of_mud["big ball of mud"].

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started.adoc
index df03541..553ab0e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started.adoc
@@ -7,17 +7,17 @@
 
 
 
-To get you up and running quickly, Apache Isis provides a xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] to setup a simple application as the basis of your own apps.
+To get you up and running quickly, Apache Isis provides a xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] to setup a simple application as the basis of your own apps.
 This is deliberately kept quite minimal so that you won't have to spend lots of time removing generated artifacts.
 On the other hand, it does set up a standard multi-module maven structure with unit- and integration tests pre-configured, as well as a webapp module so that you can easily run your app.
 We strongly recommend that you preserve this structure as you develop your own Isis application.
 
-In this chapter we also discuss the xref:ugfun.adoc#_ugfun_getting-started_datanucleus-enhancer[DataNucleus enhancer].  link:http://www.datanucleus.org/[DataNucleus] is the reference implementation of the JDO (Java data objects) spec, and Apache Isis integrates with DataNucleus as its persistence layer.
+In this chapter we also discuss the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_datanucleus-enhancer[DataNucleus enhancer].  link:http://www.datanucleus.org/[DataNucleus] is the reference implementation of the JDO (Java data objects) spec, and Apache Isis integrates with DataNucleus as its persistence layer.
 The enhancer performs post-processing on the bytecode of your persistent domain entities, such that they can be persisted by Apache Isis' JDO/DataNucleus objectstore.
 
 [NOTE]
 ====
-The xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] automatically configures the enhancer, so there's little you need to do at this stage.
+The xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] automatically configures the enhancer, so there's little you need to do at this stage.
 Even so we feel it's a good idea to be aware of this critical part of Apache Isis runtime; if the enhancer does not run, then you'll find the app fails to start with (what will seem like) quite an obscure exception message.
 ====
 
@@ -31,7 +31,7 @@ Apache Isis is a Java based framework, so in terms of prerequisites, you'll need
 * Java 7 or 8 JDK
 * link:http://maven.apache.org[Apache Maven] 3.0.5 or later
 
-You'll probably also want to use an IDE; the Apache Isis committers use either IntelliJ or Eclipse; in the xref:dg.adoc#_dg_ide[Developers' Guide] we have detailed setup instructions for using these two IDEs.
+You'll probably also want to use an IDE; the Apache Isis committers use either IntelliJ or Eclipse; in the xref:../dg/dg.adoc#_dg_ide[Developers' Guide] we have detailed setup instructions for using these two IDEs.
 If you're a NetBeans user you should have no problems as it too has strong support for Maven.
 
 When building and running within an IDE, you'll also need to configure the Datanucleus enhancer.

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_datanucleus-enhancer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_datanucleus-enhancer.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_datanucleus-enhancer.adoc
index 9b6a2d9..f6d7fdd 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_datanucleus-enhancer.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_datanucleus-enhancer.adoc
@@ -21,7 +21,7 @@ If working from the Maven command line, JDO enhancement is done using the `maven
 
 [TIP]
 ====
-The configuration described below is automatically set up by the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
+The configuration described below is automatically set up by the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
 ====
 
 
@@ -75,7 +75,7 @@ The configuration described below is automatically set up by the xref:ugfun.adoc
 </profile>
 ----
 
-The xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]  sets up the plugin correctly in the `dom` (domain object model) module.  (It's actually a little bit more complex to cater for users of the Eclipse IDE using Eclipse's m2e plugin).
+The xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]  sets up the plugin correctly in the `dom` (domain object model) module.  (It's actually a little bit more complex to cater for users of the Eclipse IDE using Eclipse's m2e plugin).
 
 
 
@@ -97,11 +97,11 @@ It's also a good idea to ensure that the `dom` module has a JDO `META-INF/persis
 ----
 <1> change as required; typically is the name of the app.
 
-Again, the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] does this.
+Again, the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] does this.
 
 [WARNING]
 ====
 If running on Windows, then there's a good chance you'll hit the http://msdn.microsoft.com/en-us/library/aa365247%28VS.85%29.aspx#maxpath[maximum path length limit].   In this case the `persistence.xml` file is mandatory rather than optional.
 
-This file is also required if you are using developing in Eclipse and relying on the DataNucleus plugin for Eclipse rather than the DataNucleus plugin for Maven.  More information can be found xref:dg.adoc#_dg_ide_eclipse[here].
+This file is also required if you are using developing in Eclipse and relying on the DataNucleus plugin for Eclipse rather than the DataNucleus plugin for Maven.  More information can be found xref:../dg/dg.adoc#_dg_ide_eclipse[here].
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_simpleapp-archetype.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_simpleapp-archetype.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_simpleapp-archetype.adoc
index c1924e3..f0a36cb 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_simpleapp-archetype.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_simpleapp-archetype.adoc
@@ -120,7 +120,7 @@ You can also take the built WAR file and deploy it into a standalone servlet con
 
 === From within the IDE
 
-Most of the time, though, you'll probably want to run the app from within your IDE.  The mechanics of doing this will vary by IDE; see the xref:dg.adoc#_dg_ide[Developers' Guide] for details of setting up Eclipse or IntelliJ IDEA.  Basically, though, it amounts to running `org.apache.isis.WebServer`, and ensuring that the xref:ugfun.adoc#_ugfun_getting-started_datanucleus-enhancer[DataNucleus enhancer] has properly processed all domain entities.
+Most of the time, though, you'll probably want to run the app from within your IDE.  The mechanics of doing this will vary by IDE; see the xref:../dg/dg.adoc#_dg_ide[Developers' Guide] for details of setting up Eclipse or IntelliJ IDEA.  Basically, though, it amounts to running `org.apache.isis.WebServer`, and ensuring that the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_datanucleus-enhancer[DataNucleus enhancer] has properly processed all domain entities.
 
 Here's what the setup looks like in IntelliJ IDEA:
 
@@ -136,7 +136,7 @@ If you are running the app from an IDE, then you can specify the fixture script
 
 image::{_imagesdir}getting-started/simpleapp-webapp-with-fixtures.png[width="600px",link="{_imagesdir}getting-started/simpleapp-webapp-with-fixtures.png"]
 
-Alternatively, you can run with a different xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`] using the `--appManifest` (or `-m`) flag.  The archetype provides
+Alternatively, you can run with a different xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`] using the `--appManifest` (or `-m`) flag.  The archetype provides
 `domainapp.app.DomainAppAppManifestWithFixtures` which specifies the aforementioned `RecreateSimpleObjects` fixture.
 
 
@@ -236,7 +236,7 @@ To log in, use `sven/pass`.
 
 Once you are familiar with the generated app, you'll want to start modifying it.  There is plenty of guidance on this site; check out the 'programming model how-tos' section on the main link:../documentation.html[documentation] page first).
 
-If you use IntelliJ IDEA or Eclipse, do also install the xref:dg.adoc#__dg_ide_intellij_live-templates[live templates (for IntelliJ)] / xref:dg.adoc#__dg_ide_eclipse_editor-templates[editor templates (for Eclipse)]; these will help you follow the Apache Isis naming conventions.
+If you use IntelliJ IDEA or Eclipse, do also install the xref:../dg/dg.adoc#__dg_ide_intellij_live-templates[live templates (for IntelliJ)] / xref:../dg/dg.adoc#__dg_ide_eclipse_editor-templates[editor templates (for Eclipse)]; these will help you follow the Apache Isis naming conventions.
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_bulk-actions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_bulk-actions.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_bulk-actions.adoc
index bcd3166..f3d5e41 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_bulk-actions.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_bulk-actions.adoc
@@ -4,5 +4,5 @@
 :_basedir: ../../
 :_imagesdir: images/
 
-NOTE: FIXME - xref:rgant.adoc#_rgant-Action_invokeOn[`@Action#invokeOn()`]
+NOTE: FIXME - xref:../rgant/rgant.adoc#_rgant-Action_invokeOn[`@Action#invokeOn()`]
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_business-rules.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_business-rules.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_business-rules.adoc
index e4b7b86..8c02ad3 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_business-rules.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_business-rules.adoc
@@ -10,7 +10,7 @@ NOTE: FIXME
 
 == Visibility ("see it")
 
-NOTE: FIXME - xref:rgcms.adoc#_rgcms_methods_prefixes_hide[`hide...()`]
+NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_hide[`hide...()`]
 
 ### Hide a Property
 
@@ -27,7 +27,7 @@ NOTE: FIXME - xref:rgcms.adoc#_rgcms_methods_prefixes_hide[`hide...()`]
 
 == Usability ("use it")
 
-NOTE: FIXME - xref:rgcms.adoc#_rgcms_methods_prefixes_disable[`disable...()`]
+NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_disable[`disable...()`]
 
 ### Disable a Property
 
@@ -53,7 +53,7 @@ In the Wicket viewer this means disabling the edit button.
 
 == Validity ("do it")
 
-NOTE: FIXME - xref:rgcms.adoc#_rgcms_methods_prefixes_validate[`validate...()`], xref:rgcms.adoc#_rgcms_methods_prefixes_validateAddTo[`validateAddTo...()`], xref:rgcms.adoc#_rgcms_methods_prefixes_validateRemoveFrom[`validateRemoveFrom...()`] and xref:rgcms.adoc#_rgcms_methods_reserved_validate[`validate()`]
+NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_validate[`validate...()`], xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_validateAddTo[`validateAddTo...()`], xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_validateRemoveFrom[`validateRemoveFrom...()`] and xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_validate[`validate()`]
 
 
 ### Validate (change to) a Property
@@ -66,7 +66,7 @@ NOTE: FIXME - xref:rgcms.adoc#_rgcms_methods_prefixes_validate[`validate...()`],
 
 ### Declarative validation
 
-NOTE: FIXME - using xref:rgant.adoc#_rgant-Parameter_mustSatisfy[`@Parameter#mustSatisfy()`], xref:rgant.adoc#_rgant-Property_mustSatisfy[`@Property#mustSatisfy()`]
+NOTE: FIXME - using xref:../rgant/rgant.adoc#_rgant-Parameter_mustSatisfy[`@Parameter#mustSatisfy()`], xref:../rgant/rgant.adoc#_rgant-Property_mustSatisfy[`@Property#mustSatisfy()`]
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_actions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_actions.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_actions.adoc
index aace483..1954d64 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_actions.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_actions.adoc
@@ -6,7 +6,7 @@
 
 
 
-While xref:ugfun.adoc#_ugfun_how-tos_class-structure_properties[properties] and xref:ugfun.adoc#_ugfun_how-tos_class-structure_collections[collections] define the state held by a domain object (its "know what" responsibilities), actions define the object's behaviour (its "know how-to" responsibilities).
+While xref:../ugfun/ugfun.adoc#_ugfun_how-tos_class-structure_properties[properties] and xref:../ugfun/ugfun.adoc#_ugfun_how-tos_class-structure_collections[collections] define the state held by a domain object (its "know what" responsibilities), actions define the object's behaviour (its "know how-to" responsibilities).
 
 An application whose domain objects have only/mostly "know-what" responsibilities is pretty dumb: it requires that the end-user know the business rules and doesn't modify the state of the domain objects such that they are invalid (for example, an "end date" being before a "start date").
 Such applications are often called CRUD applications (create/read/update/delete).
@@ -26,7 +26,7 @@ But if the state change is more complex, then most likely an action should be us
 == Defining actions
 
 Broadly speaking, actions are all the `public` methods that are not getters or setters which represent properties or collections.
-This is a slight simplification; there are a number of other method prefixes (such as `hide` or `validate`) that represent xref:ugfun.adoc#_ugfun_how-tos_business-rules[business rules]); these also not treated as actions.
+This is a slight simplification; there are a number of other method prefixes (such as `hide` or `validate`) that represent xref:../ugfun/ugfun.adoc#_ugfun_how-tos_business-rules[business rules]); these also not treated as actions.
 And, any method that are annotated with `@Programmatic` will also be excluded.
 But by and large, all other methods such as `placeOrder(...)` or `approveInvoice(...)` will be treated as actions.
 
@@ -61,7 +61,7 @@ The (non-ASF) Isis addons' http://github.com/isisaddons/isis-metamodel-paraname8
 Parameter types can be value types or reference types.
 In the case of primitive types, the end-user can just enter the value directly through the parameter field.
 In the case of reference types however (such as `Product`), a drop-down must be provided from which the end-user to select.
-This is done using either a supporting xref:rgcms.adoc#_rgcms_methods_prefixes_choices[`choices`] or xref:rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete`] method.
+This is done using either a supporting xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_choices[`choices`] or xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete`] method.
 The "choices" is used when there is a limited set of options, while "autoComplete" is used when there are large set of options such that the end-user must provide some characters to use for a search.
 
 For example, the `addToBasket(...)` action shown above might well have a :
@@ -88,7 +88,7 @@ ProductRepository productRepository;
 <1> Supporting `autoComplete` method.
 The "0" in the name means that this corresponds to parameter 0 of the "addToBasket" action (ie `Product`).
 It is also required to return a Collection of that type.
-<2> The xref:rgant.adoc#_rgant_MinLength[`@MinLength`] annotation defines how many characters the end-user must enter before performing a search.
+<2> The xref:../rgant/rgant.adoc#_rgant_MinLength[`@MinLength`] annotation defines how many characters the end-user must enter before performing a search.
 <3> The implementation delegates to an injected repository service.  This is typical.
 
 Note that it is also valid to define "choices" and "autoComplete" for value types (such as `quantity`, above); it just isn't as common to do so.
@@ -160,14 +160,14 @@ public List<Product> autoComplete0AddToBasket(@MinLength(3) String searchTerm) {
 }
 ----
 
-As the example suggests, any collection parameter type must provide a way to select items, either by way of a "choices" or "autoComplete" supporting method or alternatively defined globally using xref:rgant.adoc#_rgant_DomainObject[`@DomainObject`] on the referenced type (described xref:ugfun.adoc#__ugfun_how-tos_class-structure_actions_reference-parameter-types_removing-boilerplate[above]).
+As the example suggests, any collection parameter type must provide a way to select items, either by way of a "choices" or "autoComplete" supporting method or alternatively defined globally using xref:../rgant/rgant.adoc#_rgant_DomainObject[`@DomainObject`] on the referenced type (described xref:../ugfun/ugfun.adoc#__ugfun_how-tos_class-structure_actions_reference-parameter-types_removing-boilerplate[above]).
 
 
 [[__ugfun_how-tos_class-structure_actions_optional-parameters]]
 == Optional Parameters
 
-Whereas the xref:ugfun.adoc#__ugfun_how-tos_class-structure_properties_optional-properties[optionality of properties] is defined using xref:rgant.adoc#_rgant_Column_allowsNull[`@javax.jdo.annotations.Column#allowsNull()`], that JDO annotation cannot be applied to parameter types.
-Instead, either the xref:rgant.adoc#_rgant_Nullable[`@Nullable`] annotation or the xref:rgant.adoc#_rgant_Parameter_optionality[`@Parameter#optionality()`]  annotation/attribute is used.
+Whereas the xref:../ugfun/ugfun.adoc#__ugfun_how-tos_class-structure_properties_optional-properties[optionality of properties] is defined using xref:../rgant/rgant.adoc#_rgant_Column_allowsNull[`@javax.jdo.annotations.Column#allowsNull()`], that JDO annotation cannot be applied to parameter types.
+Instead, either the xref:../rgant/rgant.adoc#_rgant_Nullable[`@Nullable`] annotation or the xref:../rgant/rgant.adoc#_rgant_Parameter_optionality[`@Parameter#optionality()`]  annotation/attribute is used.
 
 For example:
 
@@ -190,13 +190,13 @@ public Order invoice(
 <1> Specifies the property is optional.
 <2> Specifies the corresponding parameter is optional.
 
-See also xref:ugfun.adoc#_ugfun_how-tos_class-structure_properties-vs-parameters[properties vs parameters].
+See also xref:../ugfun/ugfun.adoc#_ugfun_how-tos_class-structure_properties-vs-parameters[properties vs parameters].
 
 [[__ugfun_how-tos_class-structure_actions_string-parameters]]
 == ``String`` Parameters (Length)
 
-Whereas the xref:ugfun.adoc#__ugfun_how-tos_class-structure_properties_mapping-strings[length of string properties] is defined using xref:rgant.adoc#_rgant_Column_length[`@javax.jdo.annotations.Column#length()`], that JDO annotation cannot be applied to parameter types.
-Instead, the xref:rgant.adoc#_rgant_Parameter_maxLength[`@Parameter#maxLength()`] annotation/attribute is used.
+Whereas the xref:../ugfun/ugfun.adoc#__ugfun_how-tos_class-structure_properties_mapping-strings[length of string properties] is defined using xref:../rgant/rgant.adoc#_rgant_Column_length[`@javax.jdo.annotations.Column#length()`], that JDO annotation cannot be applied to parameter types.
+Instead, the xref:../rgant/rgant.adoc#_rgant_Parameter_maxLength[`@Parameter#maxLength()`] annotation/attribute is used.
 
 For example:
 
@@ -222,8 +222,8 @@ public Customer updateName(
     return this;
 }
 ----
-<1> Specifies the property length using the JDO xref:rgant.adoc#_rgant_Column_length[`@Column#length()`] annotation
-<2> Specifies the parameter length using the (Apache Isis) xref:rgant.adoc#_rgant_Parameter_maxLength[`@Parameter#maxLength()`] annotation
+<1> Specifies the property length using the JDO xref:../rgant/rgant.adoc#_rgant_Column_length[`@Column#length()`] annotation
+<2> Specifies the parameter length using the (Apache Isis) xref:../rgant/rgant.adoc#_rgant_Parameter_maxLength[`@Parameter#maxLength()`] annotation
 
 [IMPORTANT]
 ====
@@ -231,13 +231,13 @@ Incidentally, note in the above example that the new value is assigned to the pr
 This is important, because it allows JDO/DataNucleus to keep track that this instance variable is "dirty" and so needs flushing to the database table before the transaction completes.
 ====
 
-See also xref:ugfun.adoc#_ugfun_how-tos_class-structure_properties-vs-parameters[properties vs parameters].
+See also xref:../ugfun/ugfun.adoc#_ugfun_how-tos_class-structure_properties-vs-parameters[properties vs parameters].
 
 [[__ugfun_how-tos_class-structure_actions_bigdecimal-parameters]]
 == ``BigDecimal``s (Precision)
 
-Whereas the xref:ugfun.adoc#__ugfun_how-tos_class-structure_properties_mapping-bigdecimals[precision of BigDecimal properties] is defined using xref:rgant.adoc#_rgant_Column_scale[`@javax.jdo.annotations.Column#scale()`], that JDO annotation cannot be applied to parameter types.
-Instead, the xref:rgant.adoc#_rgant_Digits_fraction[`@javax.validation.constraints.Digits#fraction()`] annotation/attribute is used.
+Whereas the xref:../ugfun/ugfun.adoc#__ugfun_how-tos_class-structure_properties_mapping-bigdecimals[precision of BigDecimal properties] is defined using xref:../rgant/rgant.adoc#_rgant_Column_scale[`@javax.jdo.annotations.Column#scale()`], that JDO annotation cannot be applied to parameter types.
+Instead, the xref:../rgant/rgant.adoc#_rgant_Digits_fraction[`@javax.validation.constraints.Digits#fraction()`] annotation/attribute is used.
 
 For example:
 
@@ -255,10 +255,10 @@ public Order updateDiscount(
     return this;
 }
 ----
-<1> Specifies the property precision using xref:rgant.adoc#_rgant_Column_scale[`@Column#scale()`]
-<2> Specifies the corresponding parameter precision using xref:rgant.adoc#_rgant_Digits_fraction[`@Digits#fraction()`].
+<1> Specifies the property precision using xref:../rgant/rgant.adoc#_rgant_Column_scale[`@Column#scale()`]
+<2> Specifies the corresponding parameter precision using xref:../rgant/rgant.adoc#_rgant_Digits_fraction[`@Digits#fraction()`].
 
-See also xref:ugfun.adoc#_ugfun_how-tos_class-structure_properties-vs-parameters[properties vs parameters].
+See also xref:../ugfun/ugfun.adoc#_ugfun_how-tos_class-structure_properties-vs-parameters[properties vs parameters].
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_class-definition.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_class-definition.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_class-definition.adoc
index c18bab4..f88aa9c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_class-definition.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_class-definition.adoc
@@ -120,7 +120,7 @@ Domain services are generally singletons that are automatically injected into ot
 A very common usage is as a repository (to find/locate existing entities) or as a factory (to create new instances of entities).
 But services can also be exposed in the UI as top-level menus; and services are also used as a bridge to access technical resources (eg rendering a document object as a PDF).
 
-The Apache Isis framework itself also provides a large number of number of domain services, catalogued in the xref:rgsvc.adoc#[Domain Services Reference Guide].
+The Apache Isis framework itself also provides a large number of number of domain services, catalogued in the xref:../rgsvc/rgsvc.adoc#[Domain Services Reference Guide].
 Some of these are APIs (intended to be called by your application's own domain objects) and some are SPIs (implemented by your application and called by the framework, customising the way it works).
 
 The following is a typical menu service:
@@ -161,7 +161,7 @@ In the example above the menu is named "Simple Objects" (otherwise it would have
 The implementation delegates to an `SimpleObjectRepository` service, which is injected.
 <4> The `javax.inject.Inject` annotation instructs Apache Isis framework to inject the `SimpleObjectRepository` service into this domain object.
 The framework can inject into not just other domain services but will also automatically into domain entities and view models.
-There is further discussion of service injection xref:ugfun.adoc#_ugfun_how-tos_class-structure_inject-services[below].
+There is further discussion of service injection xref:../ugfun/ugfun.adoc#_ugfun_how-tos_class-structure_inject-services[below].
 
 
 [[__ugfun_how-tos_class-structure_class-definition_view-models]]

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_collections.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_collections.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_collections.adoc
index a7d663b..a01e1de 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_collections.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_collections.adoc
@@ -8,7 +8,7 @@
 A collection is an instance variable of a domain object, of a collection type that holds references to other domain objects.
 For example, a `Customer` may have a collection of ``Order``s).
 
-It's ok for a xref:ugfun.adoc#__ugfun_how-tos_class-structure_class-definition_entities[domain entity] to reference another domain entity, and for a xref:ugfun.adoc#__ugfun_how-tos_class-structure_class-definition_view-models[view model] to reference both view model and domain entities.
+It's ok for a xref:../ugfun/ugfun.adoc#__ugfun_how-tos_class-structure_class-definition_entities[domain entity] to reference another domain entity, and for a xref:../ugfun/ugfun.adoc#__ugfun_how-tos_class-structure_class-definition_view-models[view model] to reference both view model and domain entities.
 However, it isn't valid for a domain entity to hold a persisted reference to view model (DataNucleus will not know how to persist that view model).
 
 Formally speaking, a collection is simply a regular JavaBean getter, returning a collection type (subtype of `java.util.Collection`).
@@ -25,8 +25,8 @@ This and other annotations can be used to specify if the association is bidirect
 
 Apache Isis recognises some of these annotations for JDO/DataNucleus and JAXB and infers some domain semantics from them (for example, the maximum allowable length of a string property).
 
-Unlike xref:ugfun.adoc#_ugfun_how-tos_class-structure_properties[properties], the framework (at least, the xref:ugvw.adoc[Wicket viewer]) does not allow collections to be "edited".
-Instead, xref:ugfun.adoc#_ugfun_how-tos_class-structure_actions[action]s can be written that will modify the contents of the collection as a side-effect.
+Unlike xref:../ugfun/ugfun.adoc#_ugfun_how-tos_class-structure_properties[properties], the framework (at least, the xref:ugvw.adoc[Wicket viewer]) does not allow collections to be "edited".
+Instead, xref:../ugfun/ugfun.adoc#_ugfun_how-tos_class-structure_actions[action]s can be written that will modify the contents of the collection as a side-effect.
 For example, a `placeOrder(...)` action will likely add an `Order` to the `Customer#orders` collection.
 
 Since writing getter and setter methods adds quite a bit of boilerplate, it's common to use link:https://projectlombok.org/[Project Lombok] to code generate these methods at compile time (using Java's annotation processor) simply by adding the `@lombok.Getter` and `@lombok.Setter` annotations to the field.
@@ -94,6 +94,6 @@ If you do wish to use this collection type, then annotate the getter with `@Prog
 Apache Isis can (currently) only provide a UI for collections of references.
 While you can use DataNucleus to persist collections/arrays of value types, such properties must be annotated as `@Programmatic` so that they are ignored by Apache Isis.
 
-If you want to visualize an array of value types in Apache Isis, then one option is to wrap value in a view model, as explained xref:ugfun.adoc#_ugfun_how-tos_simulating-collections-of-values[elsewhere].
+If you want to visualize an array of value types in Apache Isis, then one option is to wrap value in a view model, as explained xref:../ugfun/ugfun.adoc#_ugfun_how-tos_simulating-collections-of-values[elsewhere].
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_inject-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_inject-services.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_inject-services.adoc
index 66d5ccd..26c5682 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_inject-services.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_inject-services.adoc
@@ -6,13 +6,13 @@
 
 
 Apache Isis autowires (automatically injects) domain services into each entity, as well as into the domain services themselves, using either method injection or field injection.
-The framework defines many additional services (such as xref:rgsvc.adoc#_rgsvc_api_RepositoryService[`RepositoryService`]); these are injected in exactly the same manner.
+The framework defines many additional services (such as xref:../rgsvc/rgsvc.adoc#_rgsvc_api_RepositoryService[`RepositoryService`]); these are injected in exactly the same manner.
 
 Sometimes there may be multiple services that implement a single type.
 This is common for example for SPI service, whereby one module defines an SPI service, and other module(s) in the application implement that service.
 To support this, the framework also allows lists of services to be injected.
 
-When there are multiple service implementations of a given type, the framework will inject the service with highest priority, as defined through xref:rgant.adoc#_rgant_DomainService_menuOrder[`@DomainService#menuOrder()`] (even for domain services that are not menus), lowest first.
+When there are multiple service implementations of a given type, the framework will inject the service with highest priority, as defined through xref:../rgant/rgant.adoc#_rgant_DomainService_menuOrder[`@DomainService#menuOrder()`] (even for domain services that are not menus), lowest first.
 If a list of services is injected, then that list will be ordered according to `menuOrder`, again lowest first.
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_properties.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_properties.adoc
index 34851a1..1c8bd36 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_properties.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_properties.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-A property is an instance variable of a domain object, of a scalar type, that holds some state about either a xref:ugfun.adoc#__ugfun_how-tos_class-structure_class-definition_entities[domain entity] or a xref:ugfun.adoc#__ugfun_how-tos_class-structure_class-definition_view-models[view model].
+A property is an instance variable of a domain object, of a scalar type, that holds some state about either a xref:../ugfun/ugfun.adoc#__ugfun_how-tos_class-structure_class-definition_entities[domain entity] or a xref:../ugfun/ugfun.adoc#__ugfun_how-tos_class-structure_class-definition_view-models[view model].
 
 For example, a ``Customer``'s `firstName` would be a property, as would their `accountCreationDate` that they created their account.
 All properties have at least a "getter" method, and most properties have also a "setter" method (meaning that they are mutable).
@@ -63,7 +63,7 @@ Or to map a reference type:
 private Customer customer;
 ----
 
-It's ok for a xref:ugfun.adoc#__ugfun_how-tos_class-structure_class-definition_entities[domain entity] to reference another domain entity, and for a xref:ugfun.adoc#__ugfun_how-tos_class-structure_class-definition_view-models[view model] to reference both view model and domain entities.
+It's ok for a xref:../ugfun/ugfun.adoc#__ugfun_how-tos_class-structure_class-definition_entities[domain entity] to reference another domain entity, and for a xref:../ugfun/ugfun.adoc#__ugfun_how-tos_class-structure_class-definition_view-models[view model] to reference both view model and domain entities.
 However, it isn't valid for a domain entity to hold a persisted reference to view model (DataNucleus will not know how to persist that view model).
 
 [NOTE]
@@ -72,7 +72,7 @@ For further details on mapping associations, see the JDO/DataNucleus documentati
 ====
 
 For domain entities, the annotations for mapping value types tend to be different for properties vs action parameters, because JDO annotations are only valid on properties.
-The table in the xref:ugfun.adoc#_ugfun_how-tos_class-structure_properties-vs-parameters[Properties vs Parameters] section provides a handy reference of each.
+The table in the xref:../ugfun/ugfun.adoc#_ugfun_how-tos_class-structure_properties-vs-parameters[Properties vs Parameters] section provides a handy reference of each.
 
 
 [[__ugfun_how-tos_class-structure_properties_optional-properties]]
@@ -123,7 +123,7 @@ For example:
 private String notes;
 ----
 
-If this is omitted then whether editing is enabled or disabled is defined globally, in the `isis.properties` configuration file; see xref:rgcfg.adoc#__rgcfg_configuring-core_isis-objects-editing[reference configuration guide] for further details.
+If this is omitted then whether editing is enabled or disabled is defined globally, in the `isis.properties` configuration file; see xref:../rgcfg/rgcfg.adoc#__rgcfg_configuring-core_isis-objects-editing[reference configuration guide] for further details.
 
 
 [[__ugfun_how-tos_class-structure_properties_ignoring-properties]]
@@ -254,7 +254,7 @@ More information can be found http://www.opentaps.org/docs/index.php/How_to_Use_
 
 Apache Isis configures JDO/DataNucleus so that the properties of type `org.apache.isis.applib.value.Blob` and `org.apache.isis.applib.value.Clob` can also be persisted.
 
-As for xref:ugfun.adoc#__ugfun_how-tos_class-structure_properties_mapping-joda-dates[Joda dates], this requires the `@javax.jdo.annotations.Persistent` annotation.
+As for xref:../ugfun/ugfun.adoc#__ugfun_how-tos_class-structure_properties_mapping-joda-dates[Joda dates], this requires the `@javax.jdo.annotations.Persistent` annotation.
 However, whereas for dates one would always expect this value to be retrieved eagerly, for blobs and clobs it is not so clear cut.
 
 [[__ugfun_how-tos_class-structure_properties_mapping-blobs-and-clobs_mapping-blobs]]

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_crud.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_crud.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_crud.adoc
index 95c5e64..efa18bc 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_crud.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_crud.adoc
@@ -9,21 +9,21 @@ NOTE: FIXME
 
 ## Instantiating and Persisting Objects
 
-NOTE: FIXME - using ``DomainObjectContainer``'s support for  xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-creation-api[creation] and xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-persistence-api[persistence]
+NOTE: FIXME - using ``DomainObjectContainer``'s support for  xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-creation-api[creation] and xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-persistence-api[persistence]
 
 ## Finding Objects
 
-NOTE: FIXME - using xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer_generic-repository-api[`DomainObjectContainer`]
+NOTE: FIXME - using xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer_generic-repository-api[`DomainObjectContainer`]
 
 ### Using DataNucleus type-safe queries
 
-NOTE: FIXME - as described xref:rgsvc.adoc#__rgsvc_api_IsisJdoSupport_type-safe-jdoql-queries[here]
+NOTE: FIXME - as described xref:../rgsvc/rgsvc.adoc#__rgsvc_api_IsisJdoSupport_type-safe-jdoql-queries[here]
 
 
 
 ## Deleting Objects
 
-NOTE: FIXME using ``DomainObjectContainer``'s support for  xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-persistence-api[persistence]
+NOTE: FIXME using ``DomainObjectContainer``'s support for  xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-persistence-api[persistence]
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_derived-members.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_derived-members.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_derived-members.adoc
index aacef41..abcf5e9 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_derived-members.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_derived-members.adoc
@@ -39,10 +39,10 @@ public class Customer {
 
 == Trigger on property change
 
-NOTE: FIXME - xref:rgcms.adoc#_rgcms_methods_prefixes_modify[`modify...()`], xref:rgcms.adoc#_rgcms_methods_prefixes_clear[`clear...()`]
+NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_modify[`modify...()`], xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_clear[`clear...()`]
 
 
 
 == Trigger on collection change
 
-NOTE: FIXME - xref:rgcms.adoc#_rgcms_methods_prefixes_addTo[`addTo...()`], xref:rgcms.adoc#_rgcms_methods_prefixes_removeFrom[`removeFrom...()`]
+NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_addTo[`addTo...()`], xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_removeFrom[`removeFrom...()`]

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_domain-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_domain-services.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_domain-services.adoc
index db36868..4bda8a0 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_domain-services.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_domain-services.adoc
@@ -16,14 +16,14 @@ In Apache Isis domain services have several responsibilities:
 - they provide other services (eg performing calculations, attach a barcode, send an email etc).
 - to implement an SPI of the framework, most notably cross-cutting concerns such as security, command profiling, auditing and publishing.
 
-It's worth extending the xref:ugfun.adoc#_ugfun_core-concepts_philosophy_hexagonal-architecture[Hexagonal Architecture] to show where domain services -- and in particular the domain services provided by link:http://www.isisaddons.org[Isis Addons] (non-ASF) -- fit in:
+It's worth extending the xref:../ugfun/ugfun.adoc#_ugfun_core-concepts_philosophy_hexagonal-architecture[Hexagonal Architecture] to show where domain services -- and in particular the domain services provided by link:http://www.isisaddons.org[Isis Addons] (non-ASF) -- fit in:
 
 .The hexagonal architecture with Isis addons
 image::{_imagesdir}how-tos/domain-services/hexagonal-architecture-addons.png[width="700px"]
 
 The (non-ASF) link:http://isisaddons.org[Isis Addons] are a good source of domain services, providing SPI implementations of the common cross-cutting concerns, and also a number of APIs for domain objects to invoke (eg tags, excel, settings).  Of course, you can also write your own domain services as well, for example to interface with some external CMS system, say.
 
-The Apache Isis framework also provides numerous in-built domain services.  These are catalogued in the xref:rgsvc.adoc[domain services] reference guide.
+The Apache Isis framework also provides numerous in-built domain services.  These are catalogued in the xref:../rgsvc/rgsvc.adoc[domain services] reference guide.
 
 
 
@@ -172,7 +172,7 @@ public OrderContributions {
 <2> contributed as an association, in particular as a collection because returns a `List<T>`.
 <3> Only actions with a single argument can be contributed as associations
 
-More information about contributions can be found xref:ugfun.adoc#_ugfun_how-tos_contributed-members[here].  More information
+More information about contributions can be found xref:../ugfun/ugfun.adoc#_ugfun_how-tos_contributed-members[here].  More information
 about using contributions and mixins to keep your domain application decoupled can be found xref:ugbtb.adoc#_ugbtb_decoupling_contributions[here] and xref:ugbtb.adoc#_ugbtb_decoupling_mixins[here].
 
 
@@ -207,7 +207,7 @@ public CustomerOrderSubscriptions {
 
 == Prototyping
 
-While for long-term maintainability we do recommend the naming conventions described xref:ugfun.adoc#__ugfun_how-tos_domain-services_organizing-services[above], you can get away with far fewer services when just prototyping a domain.
+While for long-term maintainability we do recommend the naming conventions described xref:../ugfun/ugfun.adoc#__ugfun_how-tos_domain-services_organizing-services[above], you can get away with far fewer services when just prototyping a domain.
 
 If the domain service nature is not specified (or is left to its default, `VIEW`), then the service's actions will
 appear in the UI both as menu items _and_ as contributions (and the service can of course be injected into other domain objects for programmatic invocation).
@@ -223,7 +223,7 @@ By default all domain services are considered to be singletons, and thread-safe.
 
 Sometimes though a service's lifetime is applicable only to a single request; in other words it is request-scoped.
 
-The CDI annotation xref:rgant.adoc#_rgant-RequestScoped[`@javax.enterprise.context.RequestScoped`] is used to indicate this fact:
+The CDI annotation xref:../rgant/rgant.adoc#_rgant-RequestScoped[`@javax.enterprise.context.RequestScoped`] is used to indicate this fact:
 
 [source,java]
 ----
@@ -233,15 +233,15 @@ public class MyService extends AbstractService {
 }
 ----
 
-The framework provides a number of request-scoped services, include a xref:rgsvc.adoc#_rgsvc_api_Scratchpad[`Scratchpad`] service query results caching through the xref:rgsvc.adoc#_rgsvc_api_QueryResultsCache[`QueryResultsCache`], and support for co-ordinating bulk actions through the xref:rgsvc.adoc#_rgsvc_api_ActionInvocationContext[`ActionInvocationContext`] service.  See the xref:rgsvc.adoc[domain services] reference guide for further details.
+The framework provides a number of request-scoped services, include a xref:../rgsvc/rgsvc.adoc#_rgsvc_api_Scratchpad[`Scratchpad`] service query results caching through the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_QueryResultsCache[`QueryResultsCache`], and support for co-ordinating bulk actions through the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ActionInvocationContext[`ActionInvocationContext`] service.  See the xref:../rgsvc/rgsvc.adoc[domain services] reference guide for further details.
 
 
 
 
 == Registering domain services
 
-The easiest way to register domain services is using xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`] to specify the modules
-which contain xref:rgant.adoc#_rgant-DomainService[`@DomainService`]-annotated classes.
+The easiest way to register domain services is using xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`] to specify the modules
+which contain xref:../rgant/rgant.adoc#_rgant-DomainService[`@DomainService`]-annotated classes.
 
 For example:
 
@@ -284,7 +284,7 @@ isis.services = employee.Employees,\
 
 This is quite rare, however; you will often want to use default implementations of domain services that are provided by the framework and so will not reside under this prefix.
 
-Examples of framework-provided services (as defined in the applib) include clock, auditing, publishing, exception handling, view model support, snapshots/mementos, and user/application settings management; see the xref:rgsvc.adoc[domain services] reference guide for further details.
+Examples of framework-provided services (as defined in the applib) include clock, auditing, publishing, exception handling, view model support, snapshots/mementos, and user/application settings management; see the xref:../rgsvc/rgsvc.adoc[domain services] reference guide for further details.
 
 
 
@@ -295,18 +295,18 @@ Services can optionally declare lifecycle callbacks to initialize them (when the
 An Apache Isis session _is_ available when initialization occurs (so services can interact with the object store, for example).
 
 
-The framework will call any `public` method annotated with xref:rgant.adoc#_rgant-PostConstruct[`@PostConstruct`] with either no arguments of an argument of type `Map<String,String>`
+The framework will call any `public` method annotated with xref:../rgant/rgant.adoc#_rgant-PostConstruct[`@PostConstruct`] with either no arguments of an argument of type `Map<String,String>`
 
 or
 
 In the latter case, the framework passes in the configuration (`isis.properties` and any other component-specific configuration files).
 
 
-Shutdown is similar; the framework will call any method annotated with xref:rgant.adoc#_rgant-PreDestroy[`@PreDestroy`].
+Shutdown is similar; the framework will call any method annotated with xref:../rgant/rgant.adoc#_rgant-PreDestroy[`@PreDestroy`].
 
 
 
 == The getId() method
 
-Optionally, a service may provide a xref:rgcms.adoc#_rgcms_methods_reserved_getId[`getId()`] method.  This method returns a logical identifier for a service, independent of its implementation.
+Optionally, a service may provide a xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_getId[`getId()`] method.  This method returns a logical identifier for a service, independent of its implementation.
 

[08/58] [abbrv] isis git commit: ISIS-1521: fixes xref links between guides

[da...@apache.org]

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_application-layer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_application-layer.adoc b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_application-layer.adoc
index a8c4cb1..839a223 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_application-layer.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_application-layer.adoc
@@ -27,7 +27,7 @@ Impl'n (g: a:)
 
 
 
-|xref:rgfis.adoc#_rgfis_spi_AuthenticationSessionProvider[`o.a.i.core.commons.` +
+|xref:../rgfis/rgfis.adoc#_rgfis_spi_AuthenticationSessionProvider[`o.a.i.core.commons.` +
 `authentication.` +
 `AuthenticationSessionProvider`]
 |Simply responsible for obtaining the current `AuthenticationSession` (the framework's internal representation of the currently logged-in user).
@@ -37,30 +37,30 @@ Impl'n (g: a:)
 |Default implementation looks up from `IsisSessionFactory` singleton's thread-local
 
 
-|xref:rgfis.adoc#_rgfis_spi_CommandDtoServiceInternal[`o.a.i.c.m.s.command` +
+|xref:../rgfis/rgfis.adoc#_rgfis_spi_CommandDtoServiceInternal[`o.a.i.c.m.s.command` +
 `CommandDtoServiceInternal`]
 |Creates memento of current action invocation, for use as a serializable XML reified command.  The
 most notable usage of this is to allow the execution of the `Command` to be deferred to run in the background (via
-xref:rgant.adoc#_rgant-Action_command[`@Action#commandExecuteIn()`] or
-xref:rgant.adoc#_rgant-Property_command[`@Property#commandExecuteIn()`].
+xref:../rgant/rgant.adoc#_rgant-Action_command[`@Action#commandExecuteIn()`] or
+xref:../rgant/rgant.adoc#_rgant-Property_command[`@Property#commandExecuteIn()`].
 |`CommandDtoService-` +
 `InternalServiceDefault` +
 ``isis-core-runtime``
 |
 
 
-|xref:rgfis.adoc#_rgfis_spi_MessageBrokerServiceInternal[`o.a.i.c.m.s.msgbroker` +
+|xref:../rgfis/rgfis.adoc#_rgfis_spi_MessageBrokerServiceInternal[`o.a.i.c.m.s.msgbroker` +
 `MessageBrokerServiceInternal`]
-|A wrapper around xref:rgsvc.adoc#_rgsvc_api_MessageService[`MessageService`].
+|A wrapper around xref:../rgsvc/rgsvc.adoc#_rgsvc_api_MessageService[`MessageService`].
 |MessageBrokerService-` +
 `InternalDefault` +
 ``isis-core-runtime``
 |This service does not provide any additional capabilities over `MessageService`, and will (most likely) be conflated with that service in the future.
 
 
-|xref:rgfis.adoc#_rgfis_spi_InteractionDtoServiceInternal[`o.a.i.c.m.s.ixn` +
+|xref:../rgfis/rgfis.adoc#_rgfis_spi_InteractionDtoServiceInternal[`o.a.i.c.m.s.ixn` +
 `InteractionDtoServiceInternal`]
-|Creates DTO for the current execution of an action invocation or property edit, for use either as a reified command or for implementations of the xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`].
+|Creates DTO for the current execution of an action invocation or property edit, for use either as a reified command or for implementations of the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`].
 |`CommandDtoService-` +
 `InternalServiceDefault` +
 ``isis-core-metamodel``

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_persistence-layer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_persistence-layer.adoc b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_persistence-layer.adoc
index 7aa1be2..e5800b2 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_persistence-layer.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_persistence-layer.adoc
@@ -27,23 +27,23 @@ Impl'n (g: a:)
 
 
 
-|xref:rgfis.adoc#_rgfis_spi_AuditingServiceInternal[`o.a.i.c.r.s.auditing.` +
+|xref:../rgfis/rgfis.adoc#_rgfis_spi_AuditingServiceInternal[`o.a.i.c.r.s.auditing.` +
 `AuditingServiceInternal`]
 |Co-ordinates between
-xref:rgfis.adoc#_rgfis_spi_ChangedObjectsServiceInternal[`ChangedObjectsServiceInternal`] and
-xref:rgfis.adoc#_rgfis_spi_AuditerService[`AuditerService`].
+xref:../rgfis/rgfis.adoc#_rgfis_spi_ChangedObjectsServiceInternal[`ChangedObjectsServiceInternal`] and
+xref:../rgfis/rgfis.adoc#_rgfis_spi_AuditerService[`AuditerService`].
 |concrete class.
 |
 
 
-|xref:rgfis.adoc#_rgfis_spi_ChangedObjectsServiceInternal[`o.a.i.c.r.s.changes.` +
+|xref:../rgfis/rgfis.adoc#_rgfis_spi_ChangedObjectsServiceInternal[`o.a.i.c.r.s.changes.` +
 `ChangedObjectsServiceInternal`]
 |Request-scoped service holding objects enlisted into current transaction.
 |concrete class.
 |
 
 
-|xref:rgfis.adoc#_rgfis_spi_PersistenceSessionServiceInternal[`o.a.i.c.m.s.` +
+|xref:../rgfis/rgfis.adoc#_rgfis_spi_PersistenceSessionServiceInternal[`o.a.i.c.m.s.` +
 `persistsession.` +
 `PersistenceSessionServiceInternal`]
 |Acts as a facade to the underlying JDO persistence session / database connection.  As such it provides methods for
@@ -54,20 +54,20 @@ querying and for persisting objects.
 |
 
 
-|xref:rgfis.adoc#_rgfis_spi_PublishingServiceInternal[`o.a.i.c.m.s.publishing.` +
+|xref:../rgfis/rgfis.adoc#_rgfis_spi_PublishingServiceInternal[`o.a.i.c.m.s.publishing.` +
 `PublishingServiceInternal`]
 |Co-ordinates between
-xref:rgfis.adoc#_rgfis_spi_ChangedObjectsServiceInternal[`ChangedObjectsServiceInternal`] and
-xref:rgsvc.adoc#_rgsvc_api_MetricsService[`MetricsService`] and the SPI services,
-xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] and (deprecated)
-xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`].
+xref:../rgfis/rgfis.adoc#_rgfis_spi_ChangedObjectsServiceInternal[`ChangedObjectsServiceInternal`] and
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_MetricsService[`MetricsService`] and the SPI services,
+xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] and (deprecated)
+xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`].
 |`PublishingService-` +
 `InternalDefault` +
 `isis-core-runtime`
 |
 
 
-|xref:rgfis.adoc#_rgfis_spi_TransactionStateProviderInternal[`o.a.i.c.m.s.` +
+|xref:../rgfis/rgfis.adoc#_rgfis_spi_TransactionStateProviderInternal[`o.a.i.c.m.s.` +
 `transtate.` +
 `TransactionStateProviderInternal`]
 |Simply provides the ability to check as to the state of the current transaction.

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_presentation-layer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_presentation-layer.adoc b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_presentation-layer.adoc
index b723ef1..a2e2248 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_presentation-layer.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_presentation-layer.adoc
@@ -27,10 +27,10 @@ Impl'n (g: a:)
 |Notes
 
 
-|xref:rgfis.adoc#_rgfis_spi_ContentNegotiationService[`o.a.i.v.ro.` +
+|xref:../rgfis/rgfis.adoc#_rgfis_spi_ContentNegotiationService[`o.a.i.v.ro.` +
 `rendering.service.conneg.` +
 `ContentNegotiationService`]
-|Encodes the algorithm that delegates to any registered xref:rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`]s.
+|Encodes the algorithm that delegates to any registered xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`]s.
 |`ContentNegotiationService-` +
 `XRoDomainType` +
 ``o.a.i.core`` +
@@ -38,10 +38,10 @@ Impl'n (g: a:)
 |
 
 
-|xref:rgfis.adoc#_rgfis_spi_RepresentationService[`o.a.i.v.ro.` +
+|xref:../rgfis/rgfis.adoc#_rgfis_spi_RepresentationService[`o.a.i.v.ro.` +
 `rendering.service.` +
 `RepresentationService`]
-|Generates the representations, delegating to any registered xref:rgfis.adoc#_rgfis_spi_ContentNegotiationService[`ContentNegotiationService`]s.
+|Generates the representations, delegating to any registered xref:../rgfis/rgfis.adoc#_rgfis_spi_ContentNegotiationService[`ContentNegotiationService`]s.
 |`RepresentationService-` +
 `ForRestfulObjects` +
 ``o.a.i.core`` +

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_AuditingServiceInternal.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_AuditingServiceInternal.adoc b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_AuditingServiceInternal.adoc
index b51fb0d..33c13ff 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_AuditingServiceInternal.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_AuditingServiceInternal.adoc
@@ -6,15 +6,15 @@
 
 
 The (internal) `AuditingServiceInternal` domain service acts as an internal facade to any
-configured xref:rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`] and
-xref:rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditerService`] services.  It is responsible for obtaining the details
+configured xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`] and
+xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditerService`] services.  It is responsible for obtaining the details
 of all changes to domain objects within an interaction, and then to call the configured `AuditingService` to actually
 create audit entries of those changes.
 
 [NOTE]
 ====
-xref:rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`] is now deprecated, replaced by
-xref:rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditerService`].
+xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`] is now deprecated, replaced by
+xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditerService`].
 ====
 
 
@@ -31,9 +31,9 @@ public class AuditingServiceInternal {
 }
 ----
 <1> minor performance optimization as to whether any auditing services are actually enabled; checks to see if
-any xref:rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`] has been configured, also if any
-xref:rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditService`] are enabled.
-<2> uses the xref:rgfis.adoc#_rgfis_spi_ChangedObjectsServiceInternal[`ChangedObjectsServiceInternal`] to obtain details of the changed properties, then call the configured xref:rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`].
+any xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`] has been configured, also if any
+xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditService`] are enabled.
+<2> uses the xref:../rgfis/rgfis.adoc#_rgfis_spi_ChangedObjectsServiceInternal[`ChangedObjectsServiceInternal`] to obtain details of the changed properties, then call the configured xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`].
 
 The service implementation is `o.a.i.c.r.s.auditing.AuditingServiceInternal`.
 
@@ -42,13 +42,13 @@ The service implementation is `o.a.i.c.r.s.auditing.AuditingServiceInternal`.
 == Registering the Service
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' default
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' default
 implementation of `AuditingServiceInternal` class is automatically registered (it is annotated with `@DomainService`)
 so no further configuration is required.
 
 
 == Related Classes
 
-The service delegates between the (internal) xref:rgfis.adoc#_rgfis_spi_ChangedObjectsServiceInternal[`ChangedObjectsServiceInternal`] domain service  to the configured xref:rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`].  If no such `AuditingService` is configured, this service is in effect a no-op.
+The service delegates between the (internal) xref:../rgfis/rgfis.adoc#_rgfis_spi_ChangedObjectsServiceInternal[`ChangedObjectsServiceInternal`] domain service  to the configured xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`].  If no such `AuditingService` is configured, this service is in effect a no-op.
 
-The (internal) xref:rgfis.adoc#_rgfis_spi_PublishingServiceInternal[`PublishingServiceInternal`] performs a similar function for the xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`], also collating details of the changed objects from `ChangedObjectsServiceInternal`.
+The (internal) xref:../rgfis/rgfis.adoc#_rgfis_spi_PublishingServiceInternal[`PublishingServiceInternal`] performs a similar function for the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`], also collating details of the changed objects from `ChangedObjectsServiceInternal`.

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_AuthenticationSessionProvider.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_AuthenticationSessionProvider.adoc b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_AuthenticationSessionProvider.adoc
index 3737a6e..d1c476e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_AuthenticationSessionProvider.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_AuthenticationSessionProvider.adoc
@@ -31,4 +31,4 @@ isisSessionFactory.getCurrentSession().getAuthenticationSession();
 ----
 
 
-If xref:rgsvc.adoc#_rgsvc_api_SudoService[`SudoService`] has been used to temporarily override the user and/or roles, then this service will report the overridden values.
+If xref:../rgsvc/rgsvc.adoc#_rgsvc_api_SudoService[`SudoService`] has been used to temporarily override the user and/or roles, then this service will report the overridden values.

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_ChangedObjectsServiceInternal.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_ChangedObjectsServiceInternal.adoc b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_ChangedObjectsServiceInternal.adoc
index 8bcea96..d69a3ec 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_ChangedObjectsServiceInternal.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_ChangedObjectsServiceInternal.adoc
@@ -8,8 +8,8 @@
 The `ChangedObjectsServiceInternal` class is an (internal) request-scoped domain service that is
 responsible for collecting the details of all changes to domain objects within an interaction.  This is then used by
 various other  (internal) domain services, notably
-xref:rgfis.adoc#_rgfis_spi_AuditingServiceInternal[`AuditingServiceInternal`] and
-xref:rgfis.adoc#_rgfis_spi_PublishingServiceInternal[`PublishingServiceInternal`].
+xref:../rgfis/rgfis.adoc#_rgfis_spi_AuditingServiceInternal[`AuditingServiceInternal`] and
+xref:../rgfis/rgfis.adoc#_rgfis_spi_PublishingServiceInternal[`PublishingServiceInternal`].
 
 
 
@@ -37,10 +37,10 @@ public class ChangedObjectsServiceInternal {
 }
 ----
 <1> Enlists an object that has just been created, updated or deleted, capturing the pre-modification values of the properties.
-<2> Used by the framework to determine whether to set the "persist hint" on the `Command` object (as per xref:rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`]).
-<3> Used by xref:rgfis.adoc#_rgfis_spi_PublishingServiceInternal[`PublishingServiceInternal`] to obtain details of and
+<2> Used by the framework to determine whether to set the "persist hint" on the `Command` object (as per xref:../rgsvc/rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`]).
+<3> Used by xref:../rgfis/rgfis.adoc#_rgfis_spi_PublishingServiceInternal[`PublishingServiceInternal`] to obtain details of and
 counters of all objects changed within the transaction.
-<4> Used by xref:rgfis.adoc#_rgfis_spi_AuditingServiceInternal[`AuditingServiceInternal`] to obtain all pairs of
+<4> Used by xref:../rgfis/rgfis.adoc#_rgfis_spi_AuditingServiceInternal[`AuditingServiceInternal`] to obtain all pairs of
 pre/post values of changed properties
 <5> Called by the framework to for clean up after auditing and publishing has completed.
 
@@ -56,7 +56,7 @@ The service implementation is `o.a.i.c.r.s.changes.ChangedObjectsServiceInternal
 == Registering the Service
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' default
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' default
 implementation of `ChangedObjectsServiceInternal` class is automatically registered (it is annotated with `@DomainService`)
 so no further configuration is required.
 
@@ -64,6 +64,6 @@ so no further configuration is required.
 
 == Related Classes
 
-Both the xref:rgfis.adoc#_rgfis_spi_AuditingServiceInternal[`AuditingServiceInternal`] and
-xref:rgfis.adoc#_rgfis_spi_PublishingServiceInternal[`PublishingServiceInternal`] (internal) domain services query
+Both the xref:../rgfis/rgfis.adoc#_rgfis_spi_AuditingServiceInternal[`AuditingServiceInternal`] and
+xref:../rgfis/rgfis.adoc#_rgfis_spi_PublishingServiceInternal[`PublishingServiceInternal`] (internal) domain services query
 this object.

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_CommandDtoServiceInternal.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_CommandDtoServiceInternal.adoc b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_CommandDtoServiceInternal.adoc
index 32a9a4e..a0e3e32 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_CommandDtoServiceInternal.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_CommandDtoServiceInternal.adoc
@@ -7,9 +7,9 @@
 
 The `CommandDtoServiceInternal` is responsible for creating an memento of the current action
 invocation or property edit, to store in the `Command` object (from
-xref:rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`]).  This memento is a JAXB DTO being an instance of the
-xref:rgcms.adoc#_rgcms_schema-cmd["cmd" schema], so can be reified so that its execution can be deferred until later,
-as a xref:rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[background command].
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`]).  This memento is a JAXB DTO being an instance of the
+xref:../rgcms/rgcms.adoc#_rgcms_schema-cmd["cmd" schema], so can be reified so that its execution can be deferred until later,
+as a xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[background command].
 
 
 
@@ -43,13 +43,13 @@ public interface CommandDtoServiceInternal {
 }
 ----
 <1> Note that this method (more precisely, `ActionInvocationMemento`) does __not__ support mixins.
-<2> Returns a JAXB DTO being an instance of the xref:rgcms.adoc#_rgcms_schema-cmd["cmd" schema] (hence convertible to
+<2> Returns a JAXB DTO being an instance of the xref:../rgcms/rgcms.adoc#_rgcms_schema-cmd["cmd" schema] (hence convertible to
 XML) that represents the __intention__ to invoke an action on a target object (or possibly many targets, for
 bulk actions).  If an action, it can also be either mixin action or a contributed action.
 <3> Returns a JAXB DTO that represents the intention to edit (set or clear) a property on a target (or possibly many
 targets, for symmetry with actions).
-<4> add the arguments of an action to an `ActionDto`.  This is used when the command is actually executed (per xref:rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`]) to populate the parameters of the equivalent `ActionInvocationDto`.
-<5> add the new value argument of a property to a `PropertyDto`.  This is used when the command is actually executed (per xref:rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`]) to set the the new value of the equivalent `PropertyEditDto`.
+<4> add the arguments of an action to an `ActionDto`.  This is used when the command is actually executed (per xref:../rgsvc/rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`]) to populate the parameters of the equivalent `ActionInvocationDto`.
+<5> add the new value argument of a property to a `PropertyDto`.  This is used when the command is actually executed (per xref:../rgsvc/rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`]) to set the the new value of the equivalent `PropertyEditDto`.
 
 
 The SPI is implemented by `o.a.i.c.r.s.command.CommandDtoServiceInternalServiceDefault`.
@@ -58,5 +58,5 @@ The SPI is implemented by `o.a.i.c.r.s.command.CommandDtoServiceInternalServiceD
 == Related Services
 
 The design of this service is similar to that of
-xref:rgfis.adoc#_rgfis_spi_InteractionDtoServiceInternal[`InteractionDtoServiceInternal`], used to create the
-`MemberExecutionDto` (from the xref:rgcms.adoc#_rgcms_schema-ixn["ixn" schema]).
+xref:../rgfis/rgfis.adoc#_rgfis_spi_InteractionDtoServiceInternal[`InteractionDtoServiceInternal`], used to create the
+`MemberExecutionDto` (from the xref:../rgcms/rgcms.adoc#_rgcms_schema-ixn["ixn" schema]).

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_ContentNegotiationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_ContentNegotiationService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_ContentNegotiationService.adoc
index 09506ef..3bd00cc 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_ContentNegotiationService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_ContentNegotiationService.adoc
@@ -26,7 +26,7 @@ If the underlying tables change (as the result of a change in their correspondin
 +
 The `ContentNegotiationService` is responsible for inspecting the HTTP `Accept` header, and use this to select the correct representation to render.  +
 +
-The Apache Isis framework provides three implementations of `ContentNegotiationService` which inspects different elements of the HTTP `Accept` header.  One of these implementations, `ContentNegotiationServiceXRoDomainType` will further delegate down to the companion xref:rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`] service (if configured/available), based on the value of the "x-ro-domain-type" parameter of the header. +
+The Apache Isis framework provides three implementations of `ContentNegotiationService` which inspects different elements of the HTTP `Accept` header.  One of these implementations, `ContentNegotiationServiceXRoDomainType` will further delegate down to the companion xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`] service (if configured/available), based on the value of the "x-ro-domain-type" parameter of the header. +
 +
 A typical implementation of `ContentMappingService` will convert the domain object into some sort of DTO (data transfer object) as specified by the "x-ro-domaintype".  If this DTO is annotated with JAXB or Jackson mappings, then the RO viewer (courtesy of the underlying link:http://resteasy.jboss.org/[RestEasy] framework) can serialize these directly. +
 +
@@ -113,7 +113,7 @@ As discussed in the introduction, the framework also provides three implementati
 ** `application/xml;profile=urn:org.restfulobjects:repr-types/action-result;x-ro-domain-type=...`
 
 
-The value of the `x-ro-domain-type` parameter corresponds to the DTO to be mapped into by the xref:rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`].
+The value of the `x-ro-domain-type` parameter corresponds to the DTO to be mapped into by the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`].
 
 If the DTO is annotated with JAXB, then also note that the runtime type must be annotated with the JAXB `javax.xml.bind.annotation.XmlRootElement` so that RestEasy is able to unambiguously serialize it.
 
@@ -171,14 +171,14 @@ image::{_imagesdir}reference-services-spi/ContentNegotiationService/accept-json.
 [_rgfis_spi_ContentNegotiationService_Configuration]]
 == Configuration
 
-The default `ContentNegotiationServiceXRoDomainType` implementation provides a xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] which controls whether a mapped domain object is pretty-printed (formatted, indented) or not:
+The default `ContentNegotiationServiceXRoDomainType` implementation provides a xref:../rgcfg/rgcfg.adoc#_rgcfg_configuring-core[configuration property] which controls whether a mapped domain object is pretty-printed (formatted, indented) or not:
 
 [source,ini]
 ----
 isis.services.ContentNegotiationServiceXRoDomainType.prettyPrint=true
 ----
 
-If the property is not set, then the default depends on the xref:rgcfg.adoc#_rgcfg_deployment-types[deployment type]; production mode will disable pretty printing, while prototyping mode will enable it.
+If the property is not set, then the default depends on the xref:../rgcfg/rgcfg.adoc#_rgcfg_deployment-types[deployment type]; production mode will disable pretty printing, while prototyping mode will enable it.
 
 
 
@@ -187,18 +187,18 @@ If the property is not set, then the default depends on the xref:rgcfg.adoc#_rgc
 == Registering the Services
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' default
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' default
 implementations of `ContentNegotiationService` service are automatically registered and injected (it is annotated with
 `@DomainService`) so no further configuration is required.
 
 To use an alternative implementation, use
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
+xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+in the xref:../rgsvc/rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
 
 
 
 == Related Services
 
-The default implementation of `ContentNegotiationService` delegates to xref:rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`] (if present) to convert domain entities into a stable form (eg DTO).
+The default implementation of `ContentNegotiationService` delegates to xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`] (if present) to convert domain entities into a stable form (eg DTO).
 
-The `ContentNegotiationService` is itself called by the (default implementation of) xref:rgfis.adoc#_rgfis_spi_RepresentationService[`RepresentationService`].
\ No newline at end of file
+The `ContentNegotiationService` is itself called by the (default implementation of) xref:../rgfis/rgfis.adoc#_rgfis_spi_RepresentationService[`RepresentationService`].
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_InteractionDtoServiceInternal.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_InteractionDtoServiceInternal.adoc b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_InteractionDtoServiceInternal.adoc
index c7680a4..fd7c6c8 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_InteractionDtoServiceInternal.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_InteractionDtoServiceInternal.adoc
@@ -6,7 +6,7 @@
 
 
 
-The `InteractionDtoServiceInternal` internal domain service is used by the framework to create and update DTOs representing member executions, ie the invocation of an action or the editing of a property.  The DTO is in all cases a subclass of `MemberExecutionDto`, from the xref:rgcms.adoc#_rgcms_schema-ixn["ixn" schema], and subsequently accessible from the `Interaction` object (per the xref:rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] service).
+The `InteractionDtoServiceInternal` internal domain service is used by the framework to create and update DTOs representing member executions, ie the invocation of an action or the editing of a property.  The DTO is in all cases a subclass of `MemberExecutionDto`, from the xref:../rgcms/rgcms.adoc#_rgcms_schema-ixn["ixn" schema], and subsequently accessible from the `Interaction` object (per the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] service).
 
 
 == SPI & Implementation
@@ -31,7 +31,7 @@ public interface InteractionDtoServiceInternal {
 }
 ----
 <1> called by the framework when invoking an action, to create a DTO capturing the details of the action invocation (target, arguments etc).
-<2> called by the framework when editing a property, to create a DTO (for the xref:rgcms.adoc#_rgcms_schema-ixn["ixn" schema]) capturing the details of the property edit (target, new value etc).
+<2> called by the framework when editing a property, to create a DTO (for the xref:../rgcms/rgcms.adoc#_rgcms_schema-ixn["ixn" schema]) capturing the details of the property edit (target, new value etc).
 <3> called by the framework to attach the result of an action invocation to the aforementioned DTO.
 
 The service is implemented by `o.a.i.core.runtime.services.ixn.InteractionDtoServiceInternalDefault`.
@@ -40,5 +40,5 @@ The service is implemented by `o.a.i.core.runtime.services.ixn.InteractionDtoSer
 == Related Services
 
 The design of this service is similar to that of
-xref:rgfis.adoc#_rgfis_spi_CommandDtoServiceInternal[`CommandDtoServiceInternal`], used to create the `CommandDto`
-(from the xref:rgcms.adoc#_rgcms_schema-cmd["cmd" schema]).
+xref:../rgfis/rgfis.adoc#_rgfis_spi_CommandDtoServiceInternal[`CommandDtoServiceInternal`], used to create the `CommandDto`
+(from the xref:../rgcms/rgcms.adoc#_rgcms_schema-cmd["cmd" schema]).

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_MessageBrokerServiceInternal.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_MessageBrokerServiceInternal.adoc b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_MessageBrokerServiceInternal.adoc
index b9d79fe..88b89cc 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_MessageBrokerServiceInternal.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_MessageBrokerServiceInternal.adoc
@@ -6,7 +6,7 @@
 
 
 The (internal) `MessageBrokerServiceInternal` domain service is a wrapper around
-xref:rgsvc.adoc#_rgsvc_api_MessageService[`MessageService`].
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_MessageService[`MessageService`].
 
 
 [NOTE]
@@ -39,6 +39,6 @@ The framework provides two implementations:
 
 * `MessageBrokerServiceInternalDefault` is provided by `isis-core-runtime`, and is used during normal use and integration tests
 
-* `MessageBrokerServiceInternalNoop` is provided as a fallback by `isis-core-metamodel`, and is provided to allow the xref:rgmvn.adoc[maven plugin] to be bootstrapped without any "backend" database.
+* `MessageBrokerServiceInternalNoop` is provided as a fallback by `isis-core-metamodel`, and is provided to allow the xref:../rgmvn/rgmvn.adoc[maven plugin] to be bootstrapped without any "backend" database.
 
 The `...Default` implementation takes priority over the `...Noop` implementation.

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_PersistenceSessionServiceInternal.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_PersistenceSessionServiceInternal.adoc b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_PersistenceSessionServiceInternal.adoc
index fdf048c..a7aee62 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_PersistenceSessionServiceInternal.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_PersistenceSessionServiceInternal.adoc
@@ -91,6 +91,6 @@ The framework provides two implementations:
 
 * `PersistenceSessionServiceInternalDefault` is provided by `isis-core-runtime`, and is used during normal use and integration tests
 
-* `PersistenceSessionServiceInternalNoop` is provided as a fallback by `isis-core-metamodel`, and is provided to allow the xref:rgmvn.adoc[maven plugin] to be bootstrapped without any "backend" database.
+* `PersistenceSessionServiceInternalNoop` is provided as a fallback by `isis-core-metamodel`, and is provided to allow the xref:../rgmvn/rgmvn.adoc[maven plugin] to be bootstrapped without any "backend" database.
 
 The `...Default` implementation takes priority over the `...Noop` implementation.

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_PublishingServiceInternal.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_PublishingServiceInternal.adoc b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_PublishingServiceInternal.adoc
index c9e1550..faab58e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_PublishingServiceInternal.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_PublishingServiceInternal.adoc
@@ -6,14 +6,14 @@
 
 
 The (internal) `PublishingServiceInternal` domain service acts as an internal facade to any
-configured xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] or (deprecated)
-xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`] domain services.
+configured xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] or (deprecated)
+xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`] domain services.
 
 For published action invocations/ property edits, it provides an API for those member executions to call.
 
 For published objects, it provides an API for the framework to call at the end of the interaction; it obtains details
 of the changed objects (from the
-xref:rgfis.adoc#_rgfis_spi_ChangedObjectsServiceInternal[`ChangedObjectsServiceInternal`]) and filters them to just
+xref:../rgfis/rgfis.adoc#_rgfis_spi_ChangedObjectsServiceInternal[`ChangedObjectsServiceInternal`]) and filters them to just
 those objects that are to be published; these are then passed through to any configured `PublisherService` or
 `PublishingService` implementations.
 
@@ -39,17 +39,17 @@ public class PublishingServiceInternal {
 }
 ----
 <1> to publish an action invocation, as represented by the specified member `Execution` parameter and with the
-xref:rgant.adoc#_rgant-Action_publishing[`@Action#publishing()`] annotation attribute or equivalent, to any configured
-xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`].  The `Execution` object will be an instance of
-`ActionInvocation` (see xref:rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] for details).
+xref:../rgant/rgant.adoc#_rgant-Action_publishing[`@Action#publishing()`] annotation attribute or equivalent, to any configured
+xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`].  The `Execution` object will be an instance of
+`ActionInvocation` (see xref:../rgsvc/rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] for details).
 <2> the remaining parameters are to support the publishing of the action to any configured
-xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`] services (deprecated).
+xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`] services (deprecated).
 <3> to publish a property edit, as as represented by the specified member `Execution` parameter and with the
-xref:rgant.adoc#_rgant-Property_publishing[`@Property#publishing()`] annotation attribute or equivalent, to any
-configured xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`].  The `Execution` object will be an instance
-of `PropertyEdit` (see xref:rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] for details).
+xref:../rgant/rgant.adoc#_rgant-Property_publishing[`@Property#publishing()`] annotation attribute or equivalent, to any
+configured xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`].  The `Execution` object will be an instance
+of `PropertyEdit` (see xref:../rgsvc/rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] for details).
 <4> to publish all changed objects that are to be published (with the
-xref:rgant.adoc#_rgant-DomainObject_publishing[`@DomainObject#publishing()`] annotation attribute or equivalent).
+xref:../rgant/rgant.adoc#_rgant-DomainObject_publishing[`@DomainObject#publishing()`] annotation attribute or equivalent).
 
 
 The service implementation is `o.a.i.c.m.s.publishing.PublishingServiceInternal`.
@@ -59,7 +59,7 @@ The service implementation is `o.a.i.c.m.s.publishing.PublishingServiceInternal`
 == Registering the Service
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' default
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' default
 implementation of `PublishingServiceInternal` class is automatically registered (it is annotated with `@DomainService`)
 so no further configuration is required.
 
@@ -67,10 +67,10 @@ so no further configuration is required.
 == Related Classes
 
 The service delegates between the (internal)
-xref:rgfis.adoc#_rgfis_spi_ChangedObjectsServiceInternal[`ChangedObjectsServiceInternal`] domain service to the
-configured xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] and
- xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`].
+xref:../rgfis/rgfis.adoc#_rgfis_spi_ChangedObjectsServiceInternal[`ChangedObjectsServiceInternal`] domain service to the
+configured xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] and
+ xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`].
 
-The (internal) xref:rgfis.adoc#_rgfis_spi_AuditingServiceInternal[`AuditingServiceInternal`] performs a similar
-function for the xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`], also collating details of the
+The (internal) xref:../rgfis/rgfis.adoc#_rgfis_spi_AuditingServiceInternal[`AuditingServiceInternal`] performs a similar
+function for the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`], also collating details of the
 changed objects from `ChangedObjectsServiceInternal`.

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_RepresentationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_RepresentationService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_RepresentationService.adoc
index 76eac5a..8977f1a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_RepresentationService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_RepresentationService.adoc
@@ -9,11 +9,11 @@
 
 The `RepresentationService` is the main plug-in point for the xref:ugvro.adoc#[RestfulObjects viewer] to generate representations.
 
-The default implementation generates representations according to the link:http://restfulobjects.org[Restful Objects spec] v1.0.  However, it also delegates to the xref:rgfis.adoc#_rgfis_spi_ContentNegotiationService[`ContentNegotiationService`] which provides a mechanism for altering representations according to the HTTP `Accept` header.
+The default implementation generates representations according to the link:http://restfulobjects.org[Restful Objects spec] v1.0.  However, it also delegates to the xref:../rgfis/rgfis.adoc#_rgfis_spi_ContentNegotiationService[`ContentNegotiationService`] which provides a mechanism for altering representations according to the HTTP `Accept` header.
 
 The principal motivation is to allow more flexible representations to be generated for REST clients that (perhaps through their use of a certain Javascript library, say) expect, or at least works best with, a certain style of representation.
 
-In all there are three domain services that can influence the representations generated: this service, xref:rgfis.adoc#_rgfis_spi_ContentNegotiationService[`ContentNegotiationService`]and the xref:rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`].  The diagram below shows how these collaborate:
+In all there are three domain services that can influence the representations generated: this service, xref:../rgfis/rgfis.adoc#_rgfis_spi_ContentNegotiationService[`ContentNegotiationService`]and the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`].  The diagram below shows how these collaborate:
 
 image::{_imagesdir}reference-services-spi/RepresentationService/service-collaborations.png[width="700px",link="{_imagesdir}reference-services-spi/RepresentationService/service-collaborations.png"]
 
@@ -75,21 +75,21 @@ ie `MemberReprMode`
 
 == Implementation
 
-As discussed in the introduction, the framework provides a default implementation, `o.a.i.v.ro.rendering.service.RepresentationServiceContentNegotiator`.   This delegates to xref:rgfis.adoc#_rgfis_spi_ContentNegotiationService[`ContentNegotiationService`] to generate an alternative representation; but if none is provided then it falls back on generating the representations as defined in the link:http://restfulobjects.org[Restful Objects spec] v1.0.
+As discussed in the introduction, the framework provides a default implementation, `o.a.i.v.ro.rendering.service.RepresentationServiceContentNegotiator`.   This delegates to xref:../rgfis/rgfis.adoc#_rgfis_spi_ContentNegotiationService[`ContentNegotiationService`] to generate an alternative representation; but if none is provided then it falls back on generating the representations as defined in the link:http://restfulobjects.org[Restful Objects spec] v1.0.
 
 To use an alternative implementation, use
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
+xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+in the xref:../rgsvc/rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
 
 
 == Registering the Services
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' default implementation of `RepresentationService` service is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' default implementation of `RepresentationService` service is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
 
 
 
 
 == Related Services
 
-The default implementation delegates to xref:rgfis.adoc#_rgfis_spi_ContentNegotiationService[`ContentNegotiationService`], whose default implementation may delegate in turn to xref:rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`] (if present).
\ No newline at end of file
+The default implementation delegates to xref:../rgfis/rgfis.adoc#_rgfis_spi_ContentNegotiationService[`ContentNegotiationService`], whose default implementation may delegate in turn to xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`] (if present).
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_TransactionStateProviderInternal.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_TransactionStateProviderInternal.adoc b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_TransactionStateProviderInternal.adoc
index 5112df1..655f8d0 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_TransactionStateProviderInternal.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_TransactionStateProviderInternal.adoc
@@ -10,7 +10,7 @@ state of the current transaction.
 
 [NOTE]
 ====
-The service will probably be combined with xref:rgsvc.adoc#_rgsvc_api_TransactionService[`TransactionService`]
+The service will probably be combined with xref:../rgsvc/rgsvc.adoc#_rgsvc_api_TransactionService[`TransactionService`]
 in the future.
 ====
 
@@ -33,6 +33,6 @@ The framework provides two implementations:
 
 * `TransactionStateProviderInternalDefault` is provided by `isis-core-runtime`, and is used during normal use and integration tests
 
-* `TransactionStateProviderInternalNoop` is provided as a fallback by `isis-core-metamodel`, and is provided to allow the xref:rgmvn.adoc[maven plugin] to be bootstrapped without any "backend" database.
+* `TransactionStateProviderInternalNoop` is provided as a fallback by `isis-core-metamodel`, and is provided to allow the xref:../rgmvn/rgmvn.adoc[maven plugin] to be bootstrapped without any "backend" database.
 
 The `...Default` implementation takes priority over the `...Noop` implementation.

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_intro.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_intro.adoc b/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_intro.adoc
index 32bc0ce..614872d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_intro.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_intro.adoc
@@ -13,17 +13,17 @@ Use to verify at build time that the metamodel of an application is valid.  This
 
 * `swagger` +
 +
-Uses the xref:rgsvc.adoc#_rgsvc_api_SwaggerService[`SwaggerService`] to generate link:http://swagger.io[Swagger] spec files that describe the public and/or private RESTful APIs exposed by the xref:ugvro.adoc#[RestfulObjects viewer].
+Uses the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_SwaggerService[`SwaggerService`] to generate link:http://swagger.io[Swagger] spec files that describe the public and/or private RESTful APIs exposed by the xref:ugvro.adoc#[RestfulObjects viewer].
 
 * `xsd` +
 +
-Uses the xref:rgsvc.adoc#_rgsvc_api_JaxbService[`JaxbService`] to generate XSD schemas from any JAXB-annotated view models/DTOs. +
+Uses the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_JaxbService[`JaxbService`] to generate XSD schemas from any JAXB-annotated view models/DTOs. +
 +
-This is instead of and preferable to using the JAXB link:https://jaxb.java.net/2.2.4/docs/schemagen.html[schemagen] tool, because it uses the framework's support (via xref:rgant.adoc#_rgant-XmlJavaTypeAdapter[`@XmlJavaTypeAdapter`]) to translate any references to domain objects into ``OidDto``s (as defined by the Apache Isis xref:rgcms.adoc#_rgcms_schema-common[common schema]).
+This is instead of and preferable to using the JAXB link:https://jaxb.java.net/2.2.4/docs/schemagen.html[schemagen] tool, because it uses the framework's support (via xref:../rgant/rgant.adoc#_rgant-XmlJavaTypeAdapter[`@XmlJavaTypeAdapter`]) to translate any references to domain objects into ``OidDto``s (as defined by the Apache Isis xref:../rgcms/rgcms.adoc#_rgcms_schema-common[common schema]).
 
 The `validate` goal is by default bound to the `test` phase, and the `swagger` goal is by default bound to the `package` phase; both are typically of your application's `dom` sub-module.  The `xsd` goal meanwhile defaults to the `generate-resources` phase, and this is generally used in a completely separate sub-module.  An example can be found in the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] example app; the separate submodule that uses the `xsd` goal is (also) called `todoapp-xsd`.
 
-All of these goals require an xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`] to point the plugin at, so that
+All of these goals require an xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`] to point the plugin at, so that
 it knows how to bootstrap an Isis runtime.  This is discussed below, followed by sections on configuring the two goals.
 
 
@@ -31,14 +31,14 @@ it knows how to bootstrap an Isis runtime.  This is discussed below, followed by
 [[__rgmvn_intro_app-manifest]]
 == `AppManifest`
 
-As noted in the introduction, all the goals require an xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`]
+As noted in the introduction, all the goals require an xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`]
 to point the plugin at, so that it knows how to bootstrap an Isis runtime.
 
 This can be extremely minimal; it isn't necessary to use the main `AppManifest` (in the `app` module) used to
 bootstrap the application, you can instead use a cut-down one.  This then allows the plugins to be run during the
 build of the `dom` module, rather than having to run in the context of the `integtest` module.
 
-For example, the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp]'s
+For example, the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp]'s
 manifest is:
 
 [source,java]

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_swagger.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_swagger.adoc b/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_swagger.adoc
index 7c5ee80..44cf269 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_swagger.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_swagger.adoc
@@ -6,7 +6,7 @@
 :toc: right
 
 
-The `swagger` goal of the `isis-maven-plugin` uses the xref:rgsvc.adoc#_rgsvc_api_SwaggerService[`SwaggerService`] to
+The `swagger` goal of the `isis-maven-plugin` uses the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_SwaggerService[`SwaggerService`] to
 generate link:http://swagger.io[Swagger] spec files to describe the public and/or private RESTful APIs exposed by the xref:ugvro.adoc#[RestfulObjects viewer].
 
 These spec files, once generated, can then be used in the build pipeline to generate client-side stubs, typically using Swagger's own link:https://github.com/swagger-api/swagger-codegen/tree/master/modules/swagger-codegen-maven-plugin[swagger-codegen-maven] plugin.
@@ -88,7 +88,7 @@ Update the `pom.xml` (in your project's `integtest` module):
 ----
 <1> the profile is active by default, though can be disabled using `-Dskip.isis-swagger`
 <2> set to `1.11.0` (or any later version)
-<3> the manifest discussed xref:rgmvn.adoc#_rgmvn_intro_app-manifest[previously]; adjust as required
+<3> the manifest discussed xref:../rgmvn/rgmvn.adoc#_rgmvn_intro_app-manifest[previously]; adjust as required
 <4> the visibilities to create (one swagger spec file per visibility listed)
 <5> which file format to generate the spec files as.
 <6> the `dom` module for the project; adjust as required

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_validate.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_validate.adoc b/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_validate.adoc
index 4f42bfb..d086a48 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_validate.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_validate.adoc
@@ -32,7 +32,7 @@ different configuration; see the final section for differences.
 
 == `dom` submodule
 
-Update the `pom.xml` (we recommend in your project's `dom` module, and with a xref:rgmvn.adoc#_rgmvn_intro_app-manifest[minimal AppManifest]):
+Update the `pom.xml` (we recommend in your project's `dom` module, and with a xref:../rgmvn/rgmvn.adoc#_rgmvn_intro_app-manifest[minimal AppManifest]):
 
 [source,xml]
 ----
@@ -80,7 +80,7 @@ Update the `pom.xml` (we recommend in your project's `dom` module, and with a xr
 ----
 <1> the profile is active by default, though can be disabled using `-Dskip.isis-validate`
 <2> set to `1.10.0` (or any later version)
-<3> the manifest discussed xref:rgmvn.adoc#_rgmvn_intro_app-manifest[previously]; adjust as required
+<3> the manifest discussed xref:../rgmvn/rgmvn.adoc#_rgmvn_intro_app-manifest[previously]; adjust as required
 <4> the `dom` module for the project; adjust as required
 <5> binds the plugin's `validate` goal to the Maven `test` lifecycle phase (ie the goal will be called when `mvn test` is run).
 
@@ -110,7 +110,7 @@ mvn test -Dskip.isis-validate
 
 == Example of failure
 
-In the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp] application the `SimpleObject` defines an `updateName` action.  This has a supporting method:
+In the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp] application the `SimpleObject` defines an `updateName` action.  This has a supporting method:
 
 
 [source,java]

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_xsd.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_xsd.adoc b/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_xsd.adoc
index 5982bd5..d4580f7 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_xsd.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_xsd.adoc
@@ -6,13 +6,13 @@
 :toc: right
 
 
-The `xsd` goal of the `isis-maven-plugin` uses the xref:rgsvc.adoc#_rgsvc_api_JaxbService[`JaxbService`] to
+The `xsd` goal of the `isis-maven-plugin` uses the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_JaxbService[`JaxbService`] to
 generate XSD schemas from any JAXB-annotated xref:ugbtb.adoc#_ugbtb_view-models[view model/DTOs].
 
 This is instead of and preferable to using the JAXB link:https://jaxb.java.net/2.2.4/docs/schemagen.html[schemagen]
 tool, because it uses the framework's support (via
-xref:rgant.adoc#_rgant-XmlJavaTypeAdapter[`@XmlJavaTypeAdapter`]) to translate any references to domain
-objects into ``OidDto``s (as defined by the Apache Isis xref:rgcms.adoc#_rgcms_schema-common[common schema]).
+xref:../rgant/rgant.adoc#_rgant-XmlJavaTypeAdapter[`@XmlJavaTypeAdapter`]) to translate any references to domain
+objects into ``OidDto``s (as defined by the Apache Isis xref:../rgcms/rgcms.adoc#_rgcms_schema-common[common schema]).
 
 The `xsd` goal defines the following properties:
 
@@ -26,11 +26,11 @@ Defaults to `generated-resources/isis-xsd`
 
 * `separate` - (optional) whether to create separate directories for each JAXB-class. +
 +
-Defaults to `false`.  Most DTO classes will reference one another or the xref:rgcms.adoc#_rgcms_schema-common[common schema].  Normally it's fine to merge all these XSDs together.  This property, if set, results in each a separate directory for each generation of its XSD or XSDs.
+Defaults to `false`.  Most DTO classes will reference one another or the xref:../rgcms/rgcms.adoc#_rgcms_schema-common[common schema].  Normally it's fine to merge all these XSDs together.  This property, if set, results in each a separate directory for each generation of its XSD or XSDs.
 
 * `commonSchemas` - (optional) whether to also generate the isis common schema(s). +
 +
-Defaults to `false`; if set then the call to xref:rgsvc.adoc#_rgsvc_api_JaxbService[`JaxbService`] will set `IsisSchemas.INCLUDE` flag.
+Defaults to `false`; if set then the call to xref:../rgsvc/rgsvc.adoc#_rgsvc_api_JaxbService[`JaxbService`] will set `IsisSchemas.INCLUDE` flag.
 
 As a convenience to any (Java) consumers, the XSDs generated from the view models can then in turn be generated
 into DTOs.  The original view models and these DTOs are similar but not identical: while the view models can only be used

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_AcceptHeaderService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_AcceptHeaderService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_AcceptHeaderService.adoc
index 38bc76c..f3fac0b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_AcceptHeaderService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_AcceptHeaderService.adoc
@@ -5,13 +5,13 @@
 :_imagesdir: images/
 
 
-The `AcceptHeaderService` domain service is a xref:rgant.adoc#_rgant-RequestScoped[`@RequestScoped`] service that
+The `AcceptHeaderService` domain service is a xref:../rgant/rgant.adoc#_rgant-RequestScoped[`@RequestScoped`] service that
 simply exposes the HTTP `Accept` header to the domain.  Its intended use is to support multiple versions of a REST API, where the responsibility for content negotiation (determining which version of the REST API is to be used) is managed by logic in the domain objects themselves.
 
 [NOTE]
 ====
-As an alternative to performing content negotiation within the domain classes, the xref:rgfis.adoc#_rgfis_spi_ContentNegotiationService[`ContentNegotiationService`] and
-xref:rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`] SPI domain services allow the framework to perform the content negotiation responsibility.
+As an alternative to performing content negotiation within the domain classes, the xref:../rgfis/rgfis.adoc#_rgfis_spi_ContentNegotiationService[`ContentNegotiationService`] and
+xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`] SPI domain services allow the framework to perform the content negotiation responsibility.
 ====
 
 == API & Implementation
@@ -27,7 +27,7 @@ public interface AcceptHeaderService {
     List<MediaType> getAcceptableMediaTypes();      // <2>
 }
 ----
-<1> is xref:rgant.adoc#_rgant-RequestScoped[`@RequestScoped`], so this domain service instance is scoped to a particular request and is then destroyed
+<1> is xref:../rgant/rgant.adoc#_rgant-RequestScoped[`@RequestScoped`], so this domain service instance is scoped to a particular request and is then destroyed
 <2> returns the list of media types found in the HTTP Accept header.
 
 
@@ -49,7 +49,7 @@ The diagram below illustrated this:
 
 image::{_imagesdir}reference-services-api/acceptheaderservice.png[width="700px",link="{_imagesdir}reference-services-api/acceptheaderservice.png"]
 
-The REST request is submitted to a domain service with a xref:rgant.adoc#_rgant-DomainService_nature[nature] of `VIEW_REST_ONLY` (`MyRestApi` in the diagram).  This uses the `AcceptHeaderService` to obtain the values of the
+The REST request is submitted to a domain service with a xref:../rgant/rgant.adoc#_rgant-DomainService_nature[nature] of `VIEW_REST_ONLY` (`MyRestApi` in the diagram).  This uses the `AcceptHeaderService` to obtain the values of the
 HTTP `Accept` header.  Based on this it delegates to the appropriate underlying domain service (with a nature of
 `DOMAIN` so that they are not exposed in the REST API at all).
 
@@ -60,7 +60,7 @@ type/subtype, eg `application/vnd.myrestapi-v1+json`; an alternative is to use a
 `application/json;x-my-rest-api-version=1` (where `x-my-rest-api-version` is the media type parameter).
 
 The Restful Objects specification does this something similar with its own `x-ro-domain-type` media type parameter;
-this is used by the xref:rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`] to determine how to
+this is used by the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`] to determine how to
 map domain objects to view models/DTOs.
 ====
 
@@ -70,10 +70,10 @@ map domain objects to view models/DTOs.
 == Registering the Service
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' default
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' default
 implementation of `AcceptHeaderService` class is automatically registered (it is annotated with `@DomainService`)
 so no further configuration is required.
 
 To use an alternative implementation, use
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
+xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+in the xref:../rgsvc/rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_ActionInvocationContext.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_ActionInvocationContext.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_ActionInvocationContext.adoc
index b9f4458..0d84ae4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_ActionInvocationContext.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_ActionInvocationContext.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-The `ActionInvocationContext` domain service is a xref:rgant.adoc#_rgant-RequestScoped[`@RequestScoped`] service intended to support the implementation of "bulk" actions annotated with xref:rgant.adoc#_rgant-Action_invokeOn[`@Action#invokeOn()`].  This allows the user to select multiple objects in a table and then invoke the same action against all of them.
+The `ActionInvocationContext` domain service is a xref:../rgant/rgant.adoc#_rgant-RequestScoped[`@RequestScoped`] service intended to support the implementation of "bulk" actions annotated with xref:../rgant/rgant.adoc#_rgant-Action_invokeOn[`@Action#invokeOn()`].  This allows the user to select multiple objects in a table and then invoke the same action against all of them.
 
 When an action is invoked in this way, this service allows each object instance to "know where it is" in the collection; it acts a little like an iterator.  In particular, an object can determine if it is the last object to be called, and so can perform special processing, eg to return a summary calculated result.
 
@@ -27,7 +27,7 @@ public static class ActionInvocationContext {
     public boolean isLast() { ... }
 }
 ----
-<1> is xref:rgant.adoc#_rgant-RequestScoped[`@RequestScoped`], so this domain service instance is scoped to a particular request and is then destroyed
+<1> is xref:../rgant/rgant.adoc#_rgant-RequestScoped[`@RequestScoped`], so this domain service instance is scoped to a particular request and is then destroyed
 <2> an enum set to either `OBJECT` (if action has been invoked on a single object) or `COLLECTION` (if has been invoked on a collection).
 <3> returns the list of domain objects which are being acted upon
 <4> is the 0-based index to the object being acted upon.
@@ -38,7 +38,7 @@ public static class ActionInvocationContext {
 
 For actions that are void or that return null, Apache Isis will return to the list once executed. But for bulk actions that are non-void, Apache Isis will render the returned object/value from the last object invoked (and simply discards the object/value of all actions except the last).
 
-One idiom is for the domain objects to also use the xref:rgsvc.adoc#_rgsvc_api_Scratchpad[`Scratchpad`] service to share information, for example to aggregate values. The `ActionInvocationContext#isLast()` method can then be used to determine if all the information has been gathered, and then do something with it (eg derive variance across a range of values, render a graph etc).
+One idiom is for the domain objects to also use the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_Scratchpad[`Scratchpad`] service to share information, for example to aggregate values. The `ActionInvocationContext#isLast()` method can then be used to determine if all the information has been gathered, and then do something with it (eg derive variance across a range of values, render a graph etc).
 
 More prosaically, the `ActionInvocationContext` can be used to ensure that the action behaves appropriately depending on how it has been invoked (on a single object and/or a collection) whether it is called in bulk mode or regular mode. Here's a snippet of code from the bulk action in the Isis addon example https://github.com/isisaddons/isis-app-todoapp/[todoapp] (not ASF):
 
@@ -66,13 +66,13 @@ public class ToDoItem ... {
 == Registering the Service
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' default
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' default
 implementation of `ActionInvocationContext` class is automatically registered (it is annotated with `@DomainService`)
 so no further configuration is required.
 
 To use an alternative implementation, use
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
+xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+in the xref:../rgsvc/rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_ApplicationFeatureRepository.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_ApplicationFeatureRepository.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_ApplicationFeatureRepository.adoc
index 489b01e..f3b5df1 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_ApplicationFeatureRepository.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_ApplicationFeatureRepository.adoc
@@ -50,13 +50,13 @@ These methods are designed primarily to return lists of strings for use in drop-
 == Registering the Service
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
 implementation of `ApplicationFeatureRepository` service is automatically registered and injected (it is annotated with
 `@DomainService`) so no further configuration is required.
 
 To use an alternative implementation, use
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
+xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+in the xref:../rgsvc/rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
 
 
 == Related Services

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_BackgroundService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_BackgroundService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_BackgroundService.adoc
index fcc31aa..103724f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_BackgroundService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_BackgroundService.adoc
@@ -6,14 +6,14 @@
 
 
 The `BackgroundService2` domain service, and also the companion
-xref:rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[`BackgroundCommandService2`] SPI service, enable commands
+xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[`BackgroundCommandService2`] SPI service, enable commands
 to be persisted such that they may be invoked in the background.
 
 The `BackgroundService2` is responsible for capturing a memento representing the command in a typesafe way,
 and persisting it rather than executing it directly.
 
 The default `BackgroundServiceDefault` implementation works by using a proxy wrapper around the target so that it can
-capture the action to invoke and its arguments.  (As of `1.13.0`), this is done using xref:rgfis.adoc#_rgfis_spi_CommandDtoServiceInternal[`CommandDtoServiceInternal`] (in previous releases it used (a private copy of) xref:rgsvc.adoc#_rgsvc_api_MementoService[`MementoService`]).
+capture the action to invoke and its arguments.  (As of `1.13.0`), this is done using xref:../rgfis/rgfis.adoc#_rgfis_spi_CommandDtoServiceInternal[`CommandDtoServiceInternal`] (in previous releases it used (a private copy of) xref:../rgsvc/rgsvc.adoc#_rgsvc_api_MementoService[`MementoService`]).
 
 The persistence delegates the persistence of the memento to an appropriate implementation of the companion
 `BackgroundCommandService2`.  One such implementation of `BackgroundCommandService` is provided by (non-ASF)
@@ -21,7 +21,7 @@ http://github.com/isisaddons/isis-module-command[Isis addons' command] module.
 
 The persisting of commands is only half the story; there needs to be a separate process to read the commands and
 execute them. The `BackgroundCommandExecution` abstract class (discussed
-xref:rgsvc.adoc#_rgsvc_api_BackgroundService_BackgroundCommandExecution[below]) provides infrastructure to do this;
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BackgroundService_BackgroundCommandExecution[below]) provides infrastructure to do this;
 the concrete implementation of this class depends on the configured `BackgroundCommandService` (in order to query for
 the persisted (background) ``Command``s.
 
@@ -38,8 +38,8 @@ public interface BackgroundService2 {
     <T> T executeMixin(Class<T> mixinClass, Object mixedIn);    // <2>
 }
 ----
-<1> returns a proxy around the domain object; any methods executed against this proxy will result in a command (to invoke the corresponding action) being persisted by xref:rgsvc.adoc#_rgsvc_spi_BackgroundCommandService2[`BackgroundCommandService2`]
-<2> Returns a proxy around the mixin; any methods executed against this proxy will result in a command (to invoke the corresponding mixin action) being persisted by xref:rgsvc.adoc#_rgsvc_spi_BackgroundCommandService2[`BackgroundCommandService2`].
+<1> returns a proxy around the domain object; any methods executed against this proxy will result in a command (to invoke the corresponding action) being persisted by xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_BackgroundCommandService2[`BackgroundCommandService2`]
+<2> Returns a proxy around the mixin; any methods executed against this proxy will result in a command (to invoke the corresponding mixin action) being persisted by xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_BackgroundCommandService2[`BackgroundCommandService2`].
 
 The default implementation is provided by core (`o.a.i.core.runtime.services.background.BackgroundServiceDefault`).
 
@@ -63,13 +63,13 @@ public void submitCustomerInvoices() {
 
 This will create a bunch of background commands executing the `submitInvoice()` action for each of the customers returned from the customer repository.
 
-The action method invoked must be part of the Apache Isis metamodel, which is to say it must be public, accept only scalar arguments, and must not be annotated with xref:rgant.adoc#_rgant-Programmatic[`@Programmatic`] or `@Ignore`. However, it may be annotated with xref:rgant.adoc#_rgant-Action_hidden[`@Action#hidden()`] or xref:rgant.adoc#_rgant-ActionLayout_hidden[`@ActionLayout#hidden()`] and it will still be invoked.
+The action method invoked must be part of the Apache Isis metamodel, which is to say it must be public, accept only scalar arguments, and must not be annotated with xref:../rgant/rgant.adoc#_rgant-Programmatic[`@Programmatic`] or `@Ignore`. However, it may be annotated with xref:../rgant/rgant.adoc#_rgant-Action_hidden[`@Action#hidden()`] or xref:../rgant/rgant.adoc#_rgant-ActionLayout_hidden[`@ActionLayout#hidden()`] and it will still be invoked.
 
 In fact, when invoked by the background service, no business rules (hidden, disabled, validation) are enforced; the action method must take responsibility for performing appropriate validation and error checking.
 
 [TIP]
 ====
-If you want to check business rules, you can use xref:rgant.adoc#_rgant-WrapperFactory[`@WrapperFactory#wrapNoExecute(...)`].
+If you want to check business rules, you can use xref:../rgant/rgant.adoc#_rgant-WrapperFactory[`@WrapperFactory#wrapNoExecute(...)`].
 ====
 
 
@@ -80,7 +80,7 @@ For the end-user, executing an action that delegates work off to the `Background
 
 One option is for the background jobs to take responsibility to notify the user themselves. In the above example, this would be the `submitInvoice()` method called upon each customer. One could imagine more complex designs where only the final command executed notifies the user.
 
-However, an alternative is to rely on the fact that the `BackgroundService` will automatically hint that the `Command` representing the original interaction (to `submitCustomerInvoices()` in the example above) should be persisted. This will be available if the related xref:rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`] and xref:rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] domain services are configured, and the `CommandService` supports persistent commands.  Note that (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module does indeed provide such an implementation of `CommandService` (as well as of the required `BackgroundCommandService`).
+However, an alternative is to rely on the fact that the `BackgroundService` will automatically hint that the `Command` representing the original interaction (to `submitCustomerInvoices()` in the example above) should be persisted. This will be available if the related xref:../rgsvc/rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`] and xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] domain services are configured, and the `CommandService` supports persistent commands.  Note that (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module does indeed provide such an implementation of `CommandService` (as well as of the required `BackgroundCommandService`).
 
 Thus, the original action can run a query to obtain it corresponding `Command`, and return this to the user. The upshot is that the child ``Command``s created by the `BackgroundService` will then be associated with `Command` for the original action.
 
@@ -97,7 +97,7 @@ public Command submitCustomerInvoices() {
 @Inject
 CommandContext commandContext;  // <1>
 ----
-<1> the injected xref:rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`] domain service.
+<1> the injected xref:../rgsvc/rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`] domain service.
 
 The user would be returned a domain object representing their action invocation.
 
@@ -107,26 +107,26 @@ The user would be returned a domain object representing their action invocation.
 == Registering the Services
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
 implementation of `BackgroundService` is automatically registered (it is annotated with `@DomainService`) so no
 further configuration is required.
 
 To use an alternative implementation, use
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
+xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+in the xref:../rgsvc/rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
 
 
 
 == Related Services
 
-This service is closely related to the xref:rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`] and also that service's supporting xref:rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] service.
+This service is closely related to the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`] and also that service's supporting xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] service.
 
 The `CommandContext` service is responsible for providing a parent `Command` with which the background ``Command``s can then be associated as children, while the `CommandService` is responsible for persisting those parent `Command`s. The latter is analogous to the way in which the `BackgroundCommandService` persists the child background `Command`s.
 
-The implementations of `CommandService` and `BackgroundCommandService` go together; typically both parent `Command`s and child background `Command`s will be persisted in the same way. The (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module provides implementations of both (see xref:rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] and xref:rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[`BackgroundCommandService`]).
+The implementations of `CommandService` and `BackgroundCommandService` go together; typically both parent `Command`s and child background `Command`s will be persisted in the same way. The (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module provides implementations of both (see xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] and xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[`BackgroundCommandService`]).
 
-The xref:rgfis.adoc#_rgfis_spi_CommandDtoServiceInternal[`CommandDtoServiceInternal`] is used to obtain
-a memento of the command such that it can be persisted.  (In earlier versions, xref:rgsvc.adoc#_rgsvc_api_MementoService[`MementoService`] was used for this purpose).
+The xref:../rgfis/rgfis.adoc#_rgfis_spi_CommandDtoServiceInternal[`CommandDtoServiceInternal`] is used to obtain
+a memento of the command such that it can be persisted.  (In earlier versions, xref:../rgsvc/rgsvc.adoc#_rgsvc_api_MementoService[`MementoService`] was used for this purpose).
 
 
 include::_rgsvc_api_BackgroundService_BackgroundCommandExecution.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_BookmarkService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_BookmarkService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_BookmarkService.adoc
index 498b9b5..895c19a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_BookmarkService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_BookmarkService.adoc
@@ -9,7 +9,7 @@ The `BookmarkService2` API provides the ability to obtain a serializable ``o.a.i
 
 For example, a `Customer` object with:
 
-* an object type of "custmgmt.Customer" (as per xref:rgant.adoc#_rgant-DomainObject_objectType[`DomainObject#objectType()`] or equivalent) , and
+* an object type of "custmgmt.Customer" (as per xref:../rgant/rgant.adoc#_rgant-DomainObject_objectType[`DomainObject#objectType()`] or equivalent) , and
 * an id=123
 
 could correspond to a `Bookmark` with a string representation of `custmgmt.Customer|123`.
@@ -24,7 +24,7 @@ For example, a `Bookmark` could be converted into a barcode, and then this used
 ``Bookmark``s are used by several other domain services as a means of storing areference to an arbitrary object
 (a polymorphic relationship).  For example, the (non-ASF)
 http://github.com/isisaddons/isis-module-auditing[Isis addons' auditing] module's implementation of
-xref:rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditerService`] uses bookmarks to capture the object
+xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditerService`] uses bookmarks to capture the object
 that is being audited.
 
 [TIP]
@@ -100,13 +100,13 @@ A more sophisticated implementation could look inside the passed `ev` argument a
 == Usage by other services
 
 Bookmarks are used by the (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module's
-implementation of  xref:rgsvc.adoc#_rgsvc_api_BackgroundCommandService[`BackgroundCommandService`], which uses a
+implementation of  xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BackgroundCommandService[`BackgroundCommandService`], which uses a
 bookmark to capture the target object on which an action will be invoked subsequently.
 
 Bookmarks are also used by the (non-ASF) http://github.com/isisaddons/isis-module-publishing[Isis addons' publishing]
-module's implementation of xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`], and by the
+module's implementation of xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`], and by the
 (non-ASF) http://github.com/isisaddons/isis-module-auditing[Isis addons' auditing] module's implementation of
-xref:rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditerService`].
+xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditerService`].
 
 
 
@@ -114,12 +114,12 @@ xref:rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditerService`].
 == Registering the Service
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
 implementation of `BookmarkService` is automatically registered (it is annotated with `@DomainService`) so no further
 configuration is required.
 
 To use an alternative implementation, use
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
+xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+in the xref:../rgsvc/rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_BulkInteractionContext.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_BulkInteractionContext.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_BulkInteractionContext.adoc
index f31c631..cb210a8 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_BulkInteractionContext.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_BulkInteractionContext.adoc
@@ -5,5 +5,5 @@
 :_imagesdir: images/
 
 
-This service is deprecated, replaced by xref:rgsvc.adoc#_rgsvc_api_ActionInvocationContext[`ActionInvocationContext`].
+This service is deprecated, replaced by xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ActionInvocationContext[`ActionInvocationContext`].
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_ClockService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_ClockService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_ClockService.adoc
index 70c6be4..e9760c1 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_ClockService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_ClockService.adoc
@@ -49,8 +49,8 @@ The default `ClockService` implementation in fact simply delegates to another cl
 
 * there are two subclasses implementations `Clock`, namely `SystemClock` and `FixtureClock`.
 * the first implementation that is instantiated registers itself as the singleton.
-* if running in xref:rgcfg.adoc#_rgcfg_deployment-types[production] (server) mode, then (unless another implementation has beaten it to the punch) the framework will instantiate the ``SystemClock`.  Once instantiated this cannot be replaced.
-* if running in xref:rgcfg.adoc#_rgcfg_deployment-types[prototype] mode, then the framework will instead instantiate `FixtureClock`.  This _can_ be replaced if required.
+* if running in xref:../rgcfg/rgcfg.adoc#_rgcfg_deployment-types[production] (server) mode, then (unless another implementation has beaten it to the punch) the framework will instantiate the ``SystemClock`.  Once instantiated this cannot be replaced.
+* if running in xref:../rgcfg/rgcfg.adoc#_rgcfg_deployment-types[prototype] mode, then the framework will instead instantiate `FixtureClock`.  This _can_ be replaced if required.
 
 The `FixtureClock` will behave as the system clock, unless its is explicitly set using `FixtureClock#setDate(...)` or `FixtureClock#setTime(...)` and so forth.
 
@@ -93,7 +93,7 @@ public class NntpClockServiceInitializer  {
 == Registering the Service
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
 implementation of `ClockService` is automatically registered (it is annotated with `@DomainService`) so no further
 configuration is required.
 

[20/58] [abbrv] isis git commit: ISIS-1521: working on ugfun.adoc

[da...@apache.org]

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_apache-isis-profile.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_apache-isis-profile.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_apache-isis-profile.adoc
new file mode 100644
index 0000000..e8632c4
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_apache-isis-profile.adoc
@@ -0,0 +1,38 @@
+: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/
+
+
+
+
+[[_ugvro_simplified-representations_apache-isis-profile]]
+= The Apache Isis "Profile"
+
+The RO spec uses the standard `Accept` header for content negotiation, and defines its own "profile" for the standard
+representations; these take the form:
+
+[source]
+----
+Accept: application/json;profile="urn:org.restfulobjects:repr-types/xxx"
+----
+
+where "xxx" varies by resource.  The detail can be found in section 2.4.1 of the RO spec.
+
+The Apache Isis viewer also defines its own "Isis" profile which enables the client to request simplified
+representations for the most frequently accessed resources.  This is done by specifying an `Accept` header of:
+
+[source]
+----
+Accept: application/json;profile="urn:org.apache.isis/v1"
+----
+
+Not every resource supports this header, but the most commonly accessed ones do.  In each case the server will set the
+`Content-Type` header so that the client knows how to process the representation.
+
+The link:https://www.youtube.com/watch?v=HMSqapQDY_4[screencast] demonstrates the feature.
+
+
+
+The sections below explain in a little more detail what is returned when this profile is activated.
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_configuration-properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_configuration-properties.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_configuration-properties.adoc
index 02862e7..4fa7155 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_configuration-properties.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_configuration-properties.adoc
@@ -1,4 +1,4 @@
-[[__ugvro_simplified-representations_configuration-properties]]
+[[_ugvro_simplified-representations_configuration-properties]]
 = Global Config Props (Deprecated)
 :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: ../../

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_domain-object.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_domain-object.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_domain-object.adoc
new file mode 100644
index 0000000..7caf15a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_domain-object.adoc
@@ -0,0 +1,92 @@
+[[_ugvro_simplified-representations_domain-object]]
+= Domain Object
+: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/
+
+
+
+
+If a domain object resource (section 14) is accessed with the Apache Isis profile, the resultant representation is a
+JSON object with simple key/value pairs for each property.
+
+The contents of any collections are also eagerly returned, consisting of an array of elements of each referenced
+object.  Each such element contains key/value pairs of each property (in other words, a grid of data is returned).
+Each element also has a special `$$href` property (so that the client can easily navigate to a resource for that
+object) and a `$$title` property (to use as a label, eg the hyperlink text).
+
+In addition, the representation defined by the RO spec is also included, under a special `$$ro` property.
+
+For example, using the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp], accessing
+this resource:
+
+[source]
+----
+http://localhost:8080/restful/objects/TODO/45
+----
+
+with an `Accept` request header of:
+
+[source]
+----
+Accept: application/json;profile="urn:org.apache.isis/v1"
+----
+
+returns the following representation:
+
+[source]
+----
+{
+  "$$href" : "http://localhost:8080/restful/objects/TODO/45",       // <1>
+  "$$instanceId" : "45",                                            // <2>
+  "$$title" : "Buy bread due by 2015-12-04",                        // <3>
+  "description" : "Buy bread",                                      // <4>
+  "category" : "Domestic",
+  "subcategory" : "Shopping",
+  "complete" : false,
+  "atPath" : "/users/sven",
+  ...
+  "similarTo" : [ {                                                 // <5>
+    "$$href" : "http://localhost:8080/restful/objects/TODO/46",
+    "$$instanceId" : "46",
+    "$$title" : "Buy milk due by 2015-12-04",
+    "description" : "Buy milk",
+    "category" : "Domestic",
+    ...
+  }, {
+    "$$href" : "http://localhost:8080/restful/objects/TODO/47",
+    "$$instanceId" : "47",
+    "$$title" : "Buy stamps due by 2015-12-04",
+    "description" : "Buy stamps",
+    "category" : "Domestic",
+    ...
+  },
+     ...
+  } ],
+  "dependencies" : [ ],
+  "$$ro" : {                                                        // <6>
+    "links" : [ ... ],
+    "extensions" : { ... },
+    "title" : "Buy bread due by 2015-12-04",
+    "domainType" : "TODO",
+    "instanceId" : "45",
+    "members" : { ... }
+  }
+}
+----
+<1> hyperlink to the representation
+<2> instance id of the domain object (unique within its type)
+<3> title of the domain object
+<4> all the properties of the domain object (to which the caller has access), as key/value pairs
+<5> contents of each collection
+<6> special `$$ro` json-prop, being the normal RO Spec representation for this object
+
+with a `Content-Type` header:
+
+[source]
+----
+Content-Type: application/json;
+              profile="urn:org.apache.isis/v1";repr-type="object"
+----
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_object-collection.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_object-collection.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_object-collection.adoc
new file mode 100644
index 0000000..d9c7a9a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_object-collection.adoc
@@ -0,0 +1,82 @@
+[[_ugvro_simplified-representations_object-collection]]
+= Domain Object Collection
+: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/
+
+
+
+If a domain object collection (section 17) is accessed with this profile, then the resultant representation is as
+an array of elements of key/value for each referenced object, and again each element the containing the key/value
+pairs of the properties of that object (a grid, again). +
+
+In addition, the representation defined by the RO spec is also included, as a special object with a single `$$ro`
+property.
+
+For example, using the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp], accessing
+this resource:
+
+[source]
+----
+http://localhost:8080/restful/objects/TODO/45/collections/similarTo
+----
+
+with an `Accept` request header of:
+
+[source]
+----
+Accept: application/json;profile="urn:org.apache.isis/v1"
+----
+
+returns the following representation:
+
+[source]
+----
+[                                                                   // <1>
+{
+  "$$href" : "http://localhost:8080/restful/objects/TODO/46",       // <2>
+  "$$instanceId" : "46",                                            // <3>
+  "$$title" : "Buy milk due by 2015-12-04",                         // <4>
+  "description" : "Buy milk",                                       // <5>
+  "category" : "Domestic",
+  ...
+}, {
+  "$$href" : "http://localhost:8080/restful/objects/TODO/47",
+  "$$title" : "Buy stamps due by 2015-12-04",
+  "description" : "Buy stamps",
+  "category" : "Domestic",
+  ...
+}, {
+  "$$href" : "http://localhost:8080/restful/objects/TODO/48",
+  "$$title" : "Mow lawn due by 2015-12-10",
+  "description" : "Mow lawn",
+  "category" : "Domestic",
+  ...
+},
+...
+, {
+  "$$ro" : {                                                        // <6>
+    "id" : "similarTo",
+    "memberType" : "collection",
+    "links" : [ ... ],
+    "extensions" : { ... },
+    "value" : [ ... ]
+  }
+}
+]
+----
+<1> returns a JSON array, not a JSON object
+<2> hyperlink to the representation
+<3> instance id of the domain object (unique within its type)
+<4> title of the domain object
+<5> all the properties of the domain object (to which the caller has access), as key/value pairs
+<6> last element is a special object with a single `$$ro` json-prop, being the normal RO Spec representation for this object
+
+with a `Content-Type` header:
+
+[source]
+----
+Content-Type: application/json;profile="urn:org.apache.isis/v1";repr-type="object-collection"
+----
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_other-representations.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_other-representations.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_other-representations.adoc
new file mode 100644
index 0000000..b5dab70
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_simplified-representations_other-representations.adoc
@@ -0,0 +1,37 @@
+[[__ugvro_simplified-representations_other-representations]]
+= Other Representations
+: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/
+
+
+
+Sometimes though you may want to extend or change the representations generated.  This might be because you want to
+write a RESTful client that uses a particular library (say a Javascript library or web components) that can only handle representations in a certain form.
+
+Or, you might want to have Apache Isis generate representations according to some other "standard", of which there are
+many:
+
+* Mike Kelly's http://stateless.co/hal_specification.html[HAL] specification
+* Mike Amundsen's http://amundsen.com/media-types/collection/[Collection+JSON] specification
+* Kevin Swiber's https://github.com/kevinswiber/siren[Siren] specification
+* Steve Klabnik's http://jsonapi.org/[JSON API] specification
+* Gregg Cainus' https://github.com/cainus/hyper-json-spec[Hyper+JSON] specification
+* the W3C's https://www.w3.org/TR/json-ld/[JSON-LD] specification
+* Markus Lanthaler's http://www.markus-lanthaler.com/hydra/[Hydra] specification.
+
+A good discussion about the relative merits of several of these different hypermedia formats can be found https://groups.google.com/forum/#!msg/api-craft/NgjzQYVOE4s/EAB2jxtU_TMJ[here].
+
+Or, of course, you may have your own internal specification that you wish to use.
+
+Supporting any of these alternative representations can be achieved by providing a suitable implementation of
+`ContentNegotiationService`.  The existing implementations (eg `ContentNegotiationServiceSimplified`) can be used as a
+starting point.
+
+[NOTE]
+====
+These will, admittedly, need to access the internal APIs for the Apache Isis metamodel, and you should be aware that
+these are not formal API; they may change over time.  That said, they are very stable and have not changed
+significantly over the last few years.
+====
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/pages/tg/_tg_stop-scaffolding-start-coding.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/pages/tg/_tg_stop-scaffolding-start-coding.adoc b/adocs/documentation/src/main/asciidoc/pages/tg/_tg_stop-scaffolding-start-coding.adoc
index ed75f22..0b56f22 100644
--- a/adocs/documentation/src/main/asciidoc/pages/tg/_tg_stop-scaffolding-start-coding.adoc
+++ b/adocs/documentation/src/main/asciidoc/pages/tg/_tg_stop-scaffolding-start-coding.adoc
@@ -300,7 +300,7 @@ The semantics of an action (whether it is safe/query only, whether it is idempot
 
 Domain entities have state: either values (primitives, strings) or references to other entities. In this section we explore adding some value properties
 
-* add some xref:../../guides/ugfun/ugfun.adoc#_ugfun_class-structure_properties[value properties]; also:
+* add some xref:../../guides/ugfun/ugfun.adoc#_ugfun_programming-model_properties[value properties]; also:
 * for string properties
 ** use the xref:../../guides/rgant/rgant.adoc#_rgant-PropertyLayout_multiLine[`@PropertyLayout(multiLine=...)`] annotation to render a text area instead of a text box
 ** use the xref:../../guides/rgant/rgant.adoc#_rgant-Property_maxLength[`@Property(maxLength=...)`] annotation to specify the maximum number of characters allowable
@@ -324,7 +324,7 @@ Domain entities have state: either values (primitives, strings) or references to
 
 Domain entities can also reference other domain entities. These references may be either scalar (single-valued) or vector (multi-valued). In this section we focus on scalar reference properties.
 
-* add some xref:../../guides/ugfun/ugfun.adoc#_ugfun_class-structure_properties[reference properties]
+* add some xref:../../guides/ugfun/ugfun.adoc#_ugfun_programming-model_properties[reference properties]
 * update the corresponding domain service (for creation actoin)
 * use different techniques to obtain references (shown in drop-down list box)
 ** use the xref:../../guides/rgant/rgant.adoc#_rgant-DomainObject_bounded[`@DomainObjectLayout(bounded=...)`] annotation on the referenced type if there are only a small number (bounded) of instances
@@ -354,7 +354,7 @@ Returning back to references, Isis also supports vector (multi-valued) reference
 * Ensure that all domain classes implement `java.lang.Comparable`
 ** use the xref:../../guides/rgcms/rgcms.adoc#_rgcms_classes_utility_ObjectContracts[`ObjectContracts`] utility class to help implement `Comparable`
 *** you can also implement `equals()`, `hashCode()`, `toString()`
-* Add a xref:../../guides/ugfun/ugfun.adoc#_ugfun_class-structure_collections[collection] to one of the entities
+* Add a xref:../../guides/ugfun/ugfun.adoc#_ugfun_programming-model_collections[collection] to one of the entities
 ** Use `SortedSet` as the class
 ** Use the xref:../../guides/rgant/rgant.adoc#_rgant-CollectionLayout_render[`@CollectionLayout(render=...)`] annotation to indicate if the collection should be visible or hidden by default
 * optional: use the xref:../../guides/rgant/rgant.adoc#_rgant-CollectionLayout_sortedBy[`@CollectionLayout(sortedBy=...)`] annotation to specify a different comparator than the natural ordering
@@ -368,7 +368,7 @@ Returning back to references, Isis also supports vector (multi-valued) reference
 The Wicket UI doesn't allow collections to be modified (added to/removed from). However, we can easily write actions to accomplish the same. Moreover, these actions can provide some additional business logic. For example: it probably shouldn't be possible to add an object twice into a collection, so it should not be presented in the list of choices/autoComplete; conversely, only those objects in the collection should be offered as choices to be removed.
 
 * Add domain actions to add/remove from the collection
-* to create objects, xref:../../guides/ugfun/ugfun.adoc#_ugfun_class-structure_inject-services[inject] associated domain service
+* to create objects, xref:../../guides/ugfun/ugfun.adoc#_ugfun_programming-model_inject-services[inject] associated domain service
 ** generally we recommend using the xref:../../guides/rgant/rgant.adoc#_rgant-Inject[`@Inject`] annotation with either private or default visibility
 * the service itself should use xref:../../guides/rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`]
 * use the xref:../../guides/rgant/rgant.adoc#_rgant-MemberOrder[`@MemberOrder(name=...)`] annotation to associate an action with a property or with a collection

[30/58] [abbrv] isis git commit: ISIS-1521: fixes further xref links between guides

[da...@apache.org]

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_cssClass.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_cssClass.adoc
index 12ac2eb..0f578bc 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_cssClass.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_cssClass.adoc
@@ -8,7 +8,7 @@
 
 The `cssClass()` returns a CSS class for a particular object instance.
 
-The xref:ugvw.adoc#[Wicket viewer] wraps the object's representation in a containing `<div>` with the class added.  This is done both for rendering the object either in a table or when rendering the object on its own page.
+The xref:../ugvw/ugvw.adoc#[Wicket viewer] wraps the object's representation in a containing `<div>` with the class added.  This is done both for rendering the object either in a table or when rendering the object on its own page.
 
 In conjunction with xref:../rgcfg/rgcfg.adoc#_rgcfg_application-specific_application-css[`application.css`], can therefore provide custom styling of an object instance wherever it is rendered. +
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_disable.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_disable.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_disable.adoc
index 765062b..46a0924 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_disable.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_disable.adoc
@@ -18,7 +18,7 @@ public String disable(Identifier.Type identifierType) { ... }
 
 where `Identifier.Type` is part of the Isis applib (nested static class of `o.a.i.applib.Identifier`) to distinguish between an interaction with an action, a property or an action.
 
-Note that Apache Isis' xref:ugbtb.adoc#_ugbtb_i18n[i18n support] extends this so that the returned reason can also be internationalized.
+Note that Apache Isis' xref:../ugbtb/ugbtb.adoc#_ugbtb_i18n[i18n support] extends this so that the returned reason can also be internationalized.
 
 For example:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_getId.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_getId.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_getId.adoc
index 4d2d081..1d7ced9 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_getId.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_getId.adoc
@@ -13,8 +13,8 @@ This can appear in several contexts, including:
 * as the value of `Bookmark#getObjectType()` and in the `toString()` value of `Bookmark`
  (see xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`])
 * in the serialization of `OidDto` in the xref:../rgcms/rgcms.adoc#_rgcms_schema-cmd[command] and xref:../rgcms/rgcms.adoc#_rgcms_schema-ixn[interaction] schemas
-* in the URLs of the xref:ugvro.adoc#[RestfulObjects viewer]
-* in the URLs of the xref:ugvw.adoc#[Wicket viewer] (specifically, for bookmarked actions)
+* in the URLs of the xref:../ugvro/ugvro.adoc#[RestfulObjects viewer]
+* in the URLs of the xref:../ugvw/ugvw.adoc#[Wicket viewer] (specifically, for bookmarked actions)
 
 
 
@@ -47,7 +47,7 @@ The rules of precedence are:
 This might be obvious, but to make explicit: we recommend that you always specify an object type for your domain services.
 
 Otherwise, if you refactor your code (change class name or move package), then any externally held references to the OID of the service will break.
-At best this will require a data migration in the database; at worst it could cause external clients accessing data through the xref:ugvro.adoc#[Restful Objects] viewer to break.
+At best this will require a data migration in the database; at worst it could cause external clients accessing data through the xref:../ugvro/ugvro.adoc#[Restful Objects] viewer to break.
 ====
 
 [NOTE]

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_iconName.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_iconName.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_iconName.adoc
index 9f5a97e..0af3731 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_iconName.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_iconName.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-Every object is represented by an icon; this is based on the domain object's simple name.  The xref:ugvw.adoc#[Wicket viewer] searches for the image in the same package as the `.class` file for the domain object or in the `images` package. It will find any matching name and one of the followign suffexes `png`, `gif`, `jpeg`, `jpg`, `svg`. If none is found, then `Default.png` will be used as fallback.
+Every object is represented by an icon; this is based on the domain object's simple name.  The xref:../ugvw/ugvw.adoc#[Wicket viewer] searches for the image in the same package as the `.class` file for the domain object or in the `images` package. It will find any matching name and one of the followign suffexes `png`, `gif`, `jpeg`, `jpg`, `svg`. If none is found, then `Default.png` will be used as fallback.
 
 The `iconName()` allows the icon that to be used to change for individual object instances.  These are usually quite subtle, for example to reflect the particular status of an object.  The value returned by the `iconName()` method is added as a suffix to the base icon name.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_title.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_title.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_title.adoc
index bd64f0e..89da56e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_title.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_title.adoc
@@ -17,7 +17,7 @@ An object's title can be constructed in various ways, but the most flexible is t
 public String title() { ... }
 ----
 
-Note that Apache Isis' xref:ugbtb.adoc#_ugbtb_i18n[i18n support] extends this so that titles can also be internationalized.
+Note that Apache Isis' xref:../ugbtb/ugbtb.adoc#_ugbtb_i18n[i18n support] extends this so that titles can also be internationalized.
 
 For example, the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] uses this technique to add an overlay for todo items that have been completed:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_validate.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_validate.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_validate.adoc
index aa73826..a361b12 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_validate.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_reserved_validate.adoc
@@ -24,4 +24,4 @@ public String validate() { ... }
 
 where the returned string is the reason that the invocation is vetoed.
 
-Note that Apache Isis' xref:ugbtb.adoc#_ugbtb_i18n[i18n support] extends this so that the returned reason can also be internationalized.
+Note that Apache Isis' xref:../ugbtb/ugbtb.adoc#_ugbtb_i18n[i18n support] extends this so that the returned reason can also be internationalized.

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_ContentNegotiationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_ContentNegotiationService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_ContentNegotiationService.adoc
index 3bd00cc..6a6df6e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_ContentNegotiationService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_ContentNegotiationService.adoc
@@ -6,7 +6,7 @@
 
 
 
-The `ContentNegotiationService` is a plug-in point for the xref:ugvro.adoc#[RestfulObjects viewer] so that it can generate representations according to HTTP `Accept` header of the request.  This idea is discussed in section 34.1 of the link:http://restfulobjects.org[Restful Objects spec] v1.0.
+The `ContentNegotiationService` is a plug-in point for the xref:../ugvro/ugvro.adoc#[RestfulObjects viewer] so that it can generate representations according to HTTP `Accept` header of the request.  This idea is discussed in section 34.1 of the link:http://restfulobjects.org[Restful Objects spec] v1.0.
 
 The principal motivation is to allow more flexible representations to be generated for REST clients that (perhaps through their use of a certain Javascript library, say) expect, or at least works best with, a certain style of representation.
 
@@ -14,11 +14,11 @@ Another use case is to support "third party" REST clients over which you have no
 
 Instead you need to create some sort of stable facade over your domain entities, one which you will preserve even if the domain entities change.  There are three ways in which you can do this:
 
-* first is to solve the problem at the domain layer by defining a regular Apache Isis xref:ugbtb.adoc#_ugbtb_view-models[view model].  This is then surfaced over the RO viewer.  +
+* first is to solve the problem at the domain layer by defining a regular Apache Isis xref:../ugbtb/ugbtb.adoc#_ugbtb_view-models[view model].  This is then surfaced over the RO viewer.  +
 +
 If the underlying entities change, then care must be taken to ensure that structure of the view model nevertheless is unchanged.
 
-* a second option is to solve the problem at the persistence layer, but defining a (SQL) view in the database and then xref:ugbtb.adoc#_ugbtb_other-techniques_mapping-rdbms-views[mapping this] to a (read-only) entity.  Again this is surfaced by the RO viewer.  +
+* a second option is to solve the problem at the persistence layer, but defining a (SQL) view in the database and then xref:../ugbtb/ugbtb.adoc#_ugbtb_other-techniques_mapping-rdbms-views[mapping this] to a (read-only) entity.  Again this is surfaced by the RO viewer.  +
 +
 If the underlying tables change (as the result of a change in their corresponding domain entities) then once more the view must be refactored so that it still presents the same structure.
 
@@ -125,7 +125,7 @@ which returns representations according to the link:http://restfulobjects.org[Re
 
 * `ContentNegotiationServiceOrgApacheIsisV1` +
 +
-which returns xref:ugvro.adoc#_ugvro_simplified-representations[simplified representations]
+which returns xref:../ugvro/ugvro.adoc#_ugvro_simplified-representations[simplified representations]
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_RepresentationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_RepresentationService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_RepresentationService.adoc
index 8977f1a..ca62d9a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_RepresentationService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_RepresentationService.adoc
@@ -7,7 +7,7 @@
 
 
 
-The `RepresentationService` is the main plug-in point for the xref:ugvro.adoc#[RestfulObjects viewer] to generate representations.
+The `RepresentationService` is the main plug-in point for the xref:../ugvro/ugvro.adoc#[RestfulObjects viewer] to generate representations.
 
 The default implementation generates representations according to the link:http://restfulobjects.org[Restful Objects spec] v1.0.  However, it also delegates to the xref:../rgfis/rgfis.adoc#_rgfis_spi_ContentNegotiationService[`ContentNegotiationService`] which provides a mechanism for altering representations according to the HTTP `Accept` header.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_intro.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_intro.adoc b/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_intro.adoc
index 614872d..a3fb8d7 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_intro.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_intro.adoc
@@ -13,7 +13,7 @@ Use to verify at build time that the metamodel of an application is valid.  This
 
 * `swagger` +
 +
-Uses the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_SwaggerService[`SwaggerService`] to generate link:http://swagger.io[Swagger] spec files that describe the public and/or private RESTful APIs exposed by the xref:ugvro.adoc#[RestfulObjects viewer].
+Uses the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_SwaggerService[`SwaggerService`] to generate link:http://swagger.io[Swagger] spec files that describe the public and/or private RESTful APIs exposed by the xref:../ugvro/ugvro.adoc#[RestfulObjects viewer].
 
 * `xsd` +
 +

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_swagger.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_swagger.adoc b/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_swagger.adoc
index 44cf269..607ee86 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_swagger.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_swagger.adoc
@@ -7,7 +7,7 @@
 
 
 The `swagger` goal of the `isis-maven-plugin` uses the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_SwaggerService[`SwaggerService`] to
-generate link:http://swagger.io[Swagger] spec files to describe the public and/or private RESTful APIs exposed by the xref:ugvro.adoc#[RestfulObjects viewer].
+generate link:http://swagger.io[Swagger] spec files to describe the public and/or private RESTful APIs exposed by the xref:../ugvro/ugvro.adoc#[RestfulObjects viewer].
 
 These spec files, once generated, can then be used in the build pipeline to generate client-side stubs, typically using Swagger's own link:https://github.com/swagger-api/swagger-codegen/tree/master/modules/swagger-codegen-maven-plugin[swagger-codegen-maven] plugin.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_validate.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_validate.adoc b/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_validate.adoc
index d086a48..51546a2 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_validate.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_validate.adoc
@@ -161,7 +161,7 @@ If one were to attempt to run the application, the same error would appear in th
 
 == Custom validation rules
 
-It is also possible to customize the validation, explained xref:ugbtb.adoc#_ugbtb_programming-model_custom-validator[here].  For example, you could enforce project-specific conventions by implementing a custom `MetaModelValidator`, and registering using a configuration property.
+It is also possible to customize the validation, explained xref:../ugbtb/ugbtb.adoc#_ugbtb_programming-model_custom-validator[here].  For example, you could enforce project-specific conventions by implementing a custom `MetaModelValidator`, and registering using a configuration property.
 
 To support this using `AppManifest`s, override its `getConfigurationProperties()` method:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_xsd.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_xsd.adoc b/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_xsd.adoc
index d4580f7..987fc6c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_xsd.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_xsd.adoc
@@ -7,7 +7,7 @@
 
 
 The `xsd` goal of the `isis-maven-plugin` uses the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_JaxbService[`JaxbService`] to
-generate XSD schemas from any JAXB-annotated xref:ugbtb.adoc#_ugbtb_view-models[view model/DTOs].
+generate XSD schemas from any JAXB-annotated xref:../ugbtb/ugbtb.adoc#_ugbtb_view-models[view model/DTOs].
 
 This is instead of and preferable to using the JAXB link:https://jaxb.java.net/2.2.4/docs/schemagen.html[schemagen]
 tool, because it uses the framework's support (via

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_AcceptHeaderService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_AcceptHeaderService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_AcceptHeaderService.adoc
index f3fac0b..61e26b4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_AcceptHeaderService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_AcceptHeaderService.adoc
@@ -35,7 +35,7 @@ The default implementation is provided by `o.a.i.v.ro.rendering.service.accepthe
 
 [NOTE]
 ====
-Note that the service will only return a list when the request is initiated through the xref:ugvro.adoc#[Restful Objects viewer].  Otherwise the service will return `null`.
+Note that the service will only return a list when the request is initiated through the xref:../ugvro/ugvro.adoc#[Restful Objects viewer].  Otherwise the service will return `null`.
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_ActionInvocationContext.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_ActionInvocationContext.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_ActionInvocationContext.adoc
index 0d84ae4..81832c9 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_ActionInvocationContext.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_ActionInvocationContext.adoc
@@ -58,7 +58,7 @@ public class ToDoItem ... {
 }
 ----
 <1> if invoked as a regular action, return this object;
-<2> otherwise (if invoked on collection of objects), return null, so that the xref:ugvw.adoc#[Wicket viewer] will re-render the list of objects
+<2> otherwise (if invoked on collection of objects), return null, so that the xref:../ugvw/ugvw.adoc#[Wicket viewer] will re-render the list of objects
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_CommandContext.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_CommandContext.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_CommandContext.adoc
index e48d0b0..970aad4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_CommandContext.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_CommandContext.adoc
@@ -38,7 +38,7 @@ The link:https://www.youtube.com/watch?v=tqXUZkPB3EI[screencast] provides a run-
 
 [NOTE]
 ====
-Note that this screencast shows an earlier version of the xref:ugvw.adoc#[Wicket viewer] UI (specifically, pre 1.8.0).
+Note that this screencast shows an earlier version of the xref:../ugvw/ugvw.adoc#[Wicket viewer] UI (specifically, pre 1.8.0).
 ====
 
 
@@ -232,7 +232,7 @@ Most of the time a `Command` will be followed directly by its corresponding `Int
 is annotated to run in the background (using xref:../rgant/rgant.adoc#_rgant-Action_command[`@Action#commandExecuteIn()`], or
 is explicitly created through the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BackgroundService[`BackgroundService`], then the actual
 interaction/execution is deferred until some other mechanism invokes the command (eg as described
-xref:ugbtb.adoc#_ugbtb_headless-access_BackgroundCommandExecution[here]).  The persistence of background commands
+xref:../ugbtb/ugbtb.adoc#_ugbtb_headless-access_BackgroundCommandExecution[here]).  The persistence of background commands
 requires a configured xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[`BackgroundCommandService`]) to actually
 persist such commands for execution.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DeepLinkService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DeepLinkService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DeepLinkService.adoc
index 25341d0..d45c7b1 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DeepLinkService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DeepLinkService.adoc
@@ -25,13 +25,13 @@ public interface DeepLinkService {
 ----
 <1> Creates a URI that can be used to obtain a representation of the provided domain object in one of the Apache Isis viewers.
 
-The xref:ugvw.adoc#[Wicket viewer] this provides an implementation for accessing the representation through this viewer.  (For the xref:ugvro.adoc#[RestfulObjects viewer], a URL can be constructed according to the link:http://www.restfulobjects.org[Restful Objects spec] in conjunction with a `Bookmark` obtained via the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`]).
+The xref:../ugvw/ugvw.adoc#[Wicket viewer] this provides an implementation for accessing the representation through this viewer.  (For the xref:../ugvro/ugvro.adoc#[RestfulObjects viewer], a URL can be constructed according to the link:http://www.restfulobjects.org[Restful Objects spec] in conjunction with a `Bookmark` obtained via the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`]).
 
 
 
 == Usage within the framework
 
-The xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_EmailNotificationService[`EmailNotificationService`] uses this service in order to generate emails as part of xref:ugvw.adoc#_ugvw_features_user-registration[user registration].
+The xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_EmailNotificationService[`EmailNotificationService`] uses this service in order to generate emails as part of xref:../ugvw/ugvw.adoc#_ugvw_features_user-registration[user registration].
 
 
 
@@ -48,7 +48,7 @@ The Wicket viewer core framework provides a default implementation of this API:
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
 `AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]), _and_ that the
-xref:ugvw.adoc#[Wicket viewer] is being used, then an implementation of `DeepLinkService` is
+xref:../ugvw/ugvw.adoc#[Wicket viewer] is being used, then an implementation of `DeepLinkService` is
 automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
 
 To use an alternative implementation, use

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DomainObjectContainer_messages-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DomainObjectContainer_messages-api.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DomainObjectContainer_messages-api.adoc
index f5802a1..c725b2a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DomainObjectContainer_messages-api.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DomainObjectContainer_messages-api.adoc
@@ -23,11 +23,11 @@ public interface DomainObjectContainer {
     ...
 }
 ----
-<1> display as a transient message to the user (not requiring acknowledgement).  In the xref:ugvw.adoc#[Wicket viewer] this is implemented as a toast that automatically disappears after a period of time.
-<2> ditto, but with translatable string, for xref:ugbtb.adoc#_ugbtb_i18n[i18n support].
-<3> warn the user about a situation with the specified message.  In the xref:ugvw.adoc#[Wicket viewer] this is implemented as a toast that must be closed by the end-user.
+<1> display as a transient message to the user (not requiring acknowledgement).  In the xref:../ugvw/ugvw.adoc#[Wicket viewer] this is implemented as a toast that automatically disappears after a period of time.
+<2> ditto, but with translatable string, for xref:../ugbtb/ugbtb.adoc#_ugbtb_i18n[i18n support].
+<3> warn the user about a situation with the specified message.  In the xref:../ugvw/ugvw.adoc#[Wicket viewer] this is implemented as a toast that must be closed by the end-user.
 <4> ditto, but with translatable string, for i18n support.
-<5> show the user an unexpected application error.  In the xref:ugvw.adoc#[Wicket viewer] this is implemented as a toast (with a different colour) that must be closed by the end-user.
+<5> show the user an unexpected application error.  In the xref:../ugvw/ugvw.adoc#[Wicket viewer] this is implemented as a toast (with a different colour) that must be closed by the end-user.
 <6> ditto, but with translatable string, for i18n support.
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DomainObjectContainer_security-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DomainObjectContainer_security-api.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DomainObjectContainer_security-api.adoc
index 2bdd0e5..96dd078 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DomainObjectContainer_security-api.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_DomainObjectContainer_security-api.adoc
@@ -42,6 +42,6 @@ public final class RoleMemento {
 }
 ----
 
-The roles associated with the `UserMemento` will be based on the configured xref:ugsec.adoc#[security] (typically Shiro).
+The roles associated with the `UserMemento` will be based on the configured xref:../ugsec/ugsec.adoc#[security] (typically Shiro).
 
-In addition, when using the xref:ugvw.adoc#[Wicket viewer] there will be an additional "org.apache.isis.viewer.wicket.roles.USER" role; this is used internally to restrict access to web pages without authenticating.
+In addition, when using the xref:../ugvw/ugvw.adoc#[Wicket viewer] there will be an additional "org.apache.isis.viewer.wicket.roles.USER" role; this is used internally to restrict access to web pages without authenticating.

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_EmailService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_EmailService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_EmailService.adoc
index 1f44047..e389417 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_EmailService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_EmailService.adoc
@@ -53,7 +53,7 @@ and these properties may optionally be configured (each has a default to use gma
 * `isis.service.email.port`
 * `isis.service.email.tls.enabled`
 
-These configuration properties can be specified either in `isis.properties` or in an xref:ugbtb.adoc#_ugbtb_deployment_externalized-configuration[external configuration file].
+These configuration properties can be specified either in `isis.properties` or in an xref:../ugbtb/ugbtb.adoc#_ugbtb_deployment_externalized-configuration[external configuration file].
 
 If prototyping (that is, running the app using `org.apache.isis.WebServer`), the configuration properties can also be specified as system properties.
 For example, if you create a test email account on gmail, you can configure the service using:
@@ -99,7 +99,7 @@ The socket connection timeout, defaulting to 2000ms.
 If you wish to write an alternative implementation, be aware that it should process the message body as HTML (as opposed to plain text or any other format).
 
 Also, note that (unlike most Apache Isis domain services) the implementation is also instantiated and injected by Google Guice.
-This is because `EmailService` is used as part of the xref:ugvw.adoc#_ugvw_features_user-registration[user registration] functionality and is used by Wicket pages that are accessed outside of the usual Apache Isis runtime.
+This is because `EmailService` is used as part of the xref:../ugvw/ugvw.adoc#_ugvw_features_user-registration[user registration] functionality and is used by Wicket pages that are accessed outside of the usual Apache Isis runtime.
 This implies a couple of additional constraints:
 
 * first, implementation class should also be annotated with `@com.google.inject.Singleton`

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_FixtureScriptsDefault.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_FixtureScriptsDefault.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_FixtureScriptsDefault.adoc
index 7e45125..25cffc1 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_FixtureScriptsDefault.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_FixtureScriptsDefault.adoc
@@ -6,7 +6,7 @@
 
 
 
-The `FixtureScriptsDefault` service provides the ability to execute xref:ugtst.adoc#_ugtst_fixture-scripts_api-and-usage[fixture scripts] .
+The `FixtureScriptsDefault` service provides the ability to execute xref:../ugtst/ugtst.adoc#_ugtst_fixture-scripts_api-and-usage[fixture scripts] .
 
 The service extends from the xref:../rgcms/rgcms.adoc#_rgcms_classes_super_FixtureScripts[`FixtureScripts`], and is only instantiated by the framework if there no custom implementation of `FixtureScripts` has been otherwise provided; in other words it is a fallback.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_GuiceBeanProvider.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_GuiceBeanProvider.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_GuiceBeanProvider.adoc
index 5a39ce3..8406df8 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_GuiceBeanProvider.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_GuiceBeanProvider.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-The `GuiceBeanProvider` domain service acts as a bridge between Apache Isis' xref:ugvw.adoc#[Wicket viewer] internal bootstrapping using link:https://github.com/google/guice[Google Guice].
+The `GuiceBeanProvider` domain service acts as a bridge between Apache Isis' xref:../ugvw/ugvw.adoc#[Wicket viewer] internal bootstrapping using link:https://github.com/google/guice[Google Guice].
 
 This service operates at a very low-level, and you are unlikely to have a need for it.  It is used internally by the framework, in the default implementation of the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DeepLinkService[`DeepLinkService`].
 
@@ -29,13 +29,13 @@ public interface GuiceBeanProvider {
 }
 ----
 
-The xref:ugvw.adoc#[Wicket viewer] this provides an implementation of this service.
+The xref:../ugvw/ugvw.adoc#[Wicket viewer] this provides an implementation of this service.
 
 
 
 == Usage
 
-Using the xref:ugvw.adoc#[Wicket viewer] requires subclassing of `IsisWicketApplication`.  In the subclass it is commonplace to override `newIsisWicketModule()`, for example:
+Using the xref:../ugvw/ugvw.adoc#[Wicket viewer] requires subclassing of `IsisWicketApplication`.  In the subclass it is commonplace to override `newIsisWicketModule()`, for example:
 
 [source,java]
 ----
@@ -81,7 +81,7 @@ should return "ToDo App".
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
 `AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]), _and_ that the
-xref:ugvw.adoc#[Wicket viewer] is being used, then an implementation of `GuiceBeanProvider` is
+xref:../ugvw/ugvw.adoc#[Wicket viewer] is being used, then an implementation of `GuiceBeanProvider` is
 automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
 
 To use an alternative implementation, use

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_InteractionContext.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_InteractionContext.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_InteractionContext.adoc
index 503640b..8b5b6f4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_InteractionContext.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_InteractionContext.adoc
@@ -200,6 +200,6 @@ Most of the time a `Command` will be followed directly by its corresponding `Int
 is annotated to run in the background (using xref:../rgant/rgant.adoc#_rgant-Action_command[`@Action#commandExecuteIn()`], or
 is explicitly created through the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BackgroundService[`BackgroundService`], then the actual
 interaction/execution is deferred until some other mechanism invokes the command (eg as described
-xref:ugbtb.adoc#_ugbtb_headless-access_BackgroundCommandExecution[here]).
+xref:../ugbtb/ugbtb.adoc#_ugbtb_headless-access_BackgroundCommandExecution[here]).
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_IsisJdoSupport.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_IsisJdoSupport.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_IsisJdoSupport.adoc
index 32e2a48..65b4b45 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_IsisJdoSupport.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_IsisJdoSupport.adoc
@@ -132,7 +132,7 @@ private static <T> List<T> executeListAndClose(final TypesafeQuery<T> query) {
 [[__rgsvc_api_IsisJdoSupport_fixture-support]]
 == Fixture support
 
-When writing xref:ugtst.adoc#_ugtst_integ-test-support[integration tests] you'll usually need to tear down some/all mutable transactional data before each test.  One way to do that is to use the `executeUpdate(...)` method described xref:../rgsvc/rgsvc.adoc#__rgsvc_api_IsisJdoSupport_executing-sql[above].
+When writing xref:../ugtst/ugtst.adoc#_ugtst_integ-test-support[integration tests] you'll usually need to tear down some/all mutable transactional data before each test.  One way to do that is to use the `executeUpdate(...)` method described xref:../rgsvc/rgsvc.adoc#__rgsvc_api_IsisJdoSupport_executing-sql[above].
 
 Alternatively, the `deleteAll(...)` method will let your test delete all instances of a class without resorting to SQL:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_JaxbService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_JaxbService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_JaxbService.adoc
index 9e99ef3..1cc6cc1 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_JaxbService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_JaxbService.adoc
@@ -50,7 +50,7 @@ Isis provides a default implementation of the service, `o.a.i.schema.services.ja
 
 This service is provided as a convenience for applications, but is also used internally by the framework to
 xref:../rgant/rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`]-annotated
-xref:ugbtb.adoc#_ugbtb_view-models[view models].  The functionality to download XML and XSD schemas is also
+xref:../ugbtb/ugbtb.adoc#_ugbtb_view-models[view models].  The functionality to download XML and XSD schemas is also
 exposed in the UI through mixins to xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins_Dto[`Dto`] interface.
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_MementoService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_MementoService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_MementoService.adoc
index 15f5f60..11caf67 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_MementoService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_MementoService.adoc
@@ -7,8 +7,8 @@
 
 
 The `MementoService` was originally introduced to simplify the implementation of
-xref:ugbtb.adoc#_ugbtb_view-models[ViewModel]s which are required by the framework to return string representation of
-all of their backing state, moreover which is safe for use within a URL.  This usage is deprecated; use xref:ugbtb.adoc#_ugbtb_view-models_jaxb[JAXB view models] instead.
+xref:../ugbtb/ugbtb.adoc#_ugbtb_view-models[ViewModel]s which are required by the framework to return string representation of
+all of their backing state, moreover which is safe for use within a URL.  This usage is deprecated; use xref:../ugbtb/ugbtb.adoc#_ugbtb_view-models_jaxb[JAXB view models] instead.
 
 The service can also be used to create a memento of arbitrary objects, however this usage is also deprecated.  (Prior
 to `1.13.0` it was used internally by the core implementation of

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_MessageService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_MessageService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_MessageService.adoc
index 7cb42ff..a219987 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_MessageService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_MessageService.adoc
@@ -32,11 +32,11 @@ public interface MessageService {
     ...
 }
 ----
-<1> display as a transient message to the user (not requiring acknowledgement).  In the xref:ugvw.adoc#[Wicket viewer] this is implemented as a toast that automatically disappears after a period of time.
-<2> ditto, but with translatable string, for xref:ugbtb.adoc#_ugbtb_i18n[i18n support].
-<3> warn the user about a situation with the specified message.  In the xref:ugvw.adoc#[Wicket viewer] this is implemented as a toast that must be closed by the end-user.
+<1> display as a transient message to the user (not requiring acknowledgement).  In the xref:../ugvw/ugvw.adoc#[Wicket viewer] this is implemented as a toast that automatically disappears after a period of time.
+<2> ditto, but with translatable string, for xref:../ugbtb/ugbtb.adoc#_ugbtb_i18n[i18n support].
+<3> warn the user about a situation with the specified message.  In the xref:../ugvw/ugvw.adoc#[Wicket viewer] this is implemented as a toast that must be closed by the end-user.
 <4> ditto, but with translatable string, for i18n support.
-<5> show the user an unexpected application error.  In the xref:ugvw.adoc#[Wicket viewer] this is implemented as a toast (with a different colour) that must be closed by the end-user.
+<5> show the user an unexpected application error.  In the xref:../ugvw/ugvw.adoc#[Wicket viewer] this is implemented as a toast (with a different colour) that must be closed by the end-user.
 <6> ditto, but with translatable string, for i18n support.
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_Scratchpad.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_Scratchpad.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_Scratchpad.adoc
index d6e09d9..f513b20 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_Scratchpad.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_Scratchpad.adoc
@@ -59,7 +59,7 @@ public BigDecimal totalCost() {
 Scratchpad scratchpad;
 ----
 
-A more complex example could use a xref:ugbtb.adoc#_ugbtb_view-models[view model] to enable bulk updates to a set of objects. The view model's job is to gather track of the items to be updated:
+A more complex example could use a xref:../ugbtb/ugbtb.adoc#_ugbtb_view-models[view model] to enable bulk updates to a set of objects. The view model's job is to gather track of the items to be updated:
 
 [source,java]
 ----
@@ -100,7 +100,7 @@ Scratchpad scratchpad;
 <1> look for the `ToDoItemBulkUpdate` in the scratchpad...
 <2> ... and add one if there isn't one (ie for the first object returned).
 
-If using the xref:ugvw.adoc#[Wicket viewer], the `ToDoItemBulkUpdate` view model returned from the last action invoked will be displayed. Thereafter this view model can be used to perform a bulk update of the "enlisted" items.
+If using the xref:../ugvw/ugvw.adoc#[Wicket viewer], the `ToDoItemBulkUpdate` view model returned from the last action invoked will be displayed. Thereafter this view model can be used to perform a bulk update of the "enlisted" items.
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_SudoService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_SudoService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_SudoService.adoc
index d07b8c3..a95214c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_SudoService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_SudoService.adoc
@@ -7,7 +7,7 @@
 
 
 The `SudoService` allows the current user reported by the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_UserService[`UserService`]  to be temporarily changed to some other user.
-This is useful both for xref:ugtst.adoc#_ugtst_integ-test-support[integration testing] (eg if testing a workflow system whereby objects are moved from one user to another) and while running xref:ugtst.adoc#_ugtst_fixture-scripts[fixture scripts] (eg setting up objects that would normally require several users to have acted upon the objects).
+This is useful both for xref:../ugtst/ugtst.adoc#_ugtst_integ-test-support[integration testing] (eg if testing a workflow system whereby objects are moved from one user to another) and while running xref:../ugtst/ugtst.adoc#_ugtst_fixture-scripts[fixture scripts] (eg setting up objects that would normally require several users to have acted upon the objects).
 
 
 == API
@@ -36,7 +36,7 @@ The current user/role reported by the internal xref:../rgfis/rgfis.adoc#_rgfis_s
 
 [IMPORTANT]
 ====
-Note however that this the "effective user" does not propagate through to the xref:ugsec.adoc#[Shiro security mechanism], which will continue to be evaluated according to the permissions of the current user.
+Note however that this the "effective user" does not propagate through to the xref:../ugsec/ugsec.adoc#[Shiro security mechanism], which will continue to be evaluated according to the permissions of the current user.
 See the xref:../rgsvc/rgsvc.adoc#__rgsvc_api_SudoService_ACCESS-ALL-ROLE[`ACCESS-ALL-ROLE`] below for details of how to circumvent this.
 ====
 
@@ -70,7 +70,7 @@ protected void execute(final ExecutionContext ec) {
 [[__rgsvc_api_SudoService_ACCESS-ALL-ROLE]]
 === ACCESS_ALL_ROLE
 
-When `sudo(...)` is called the "effective user" is reported by both xref:../rgsvc/rgsvc.adoc#_rgsvc_api_UserService[`UserService`] and by xref:../rgfis/rgfis.adoc#_rgfis_spi_AuthenticationSessionProvider[`AuthenticationSessionProvider`], but does not propagate through to the xref:ugsec.adoc#[Shiro security mechanism].
+When `sudo(...)` is called the "effective user" is reported by both xref:../rgsvc/rgsvc.adoc#_rgsvc_api_UserService[`UserService`] and by xref:../rgfis/rgfis.adoc#_rgfis_spi_AuthenticationSessionProvider[`AuthenticationSessionProvider`], but does not propagate through to the xref:../ugsec/ugsec.adoc#[Shiro security mechanism].
 These continue to be evaluated according to the permissions of the current user.
 
 This can be a problem in certain use cases.

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_SwaggerService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_SwaggerService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_SwaggerService.adoc
index f16f083..03109c9 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_SwaggerService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_SwaggerService.adoc
@@ -6,13 +6,13 @@
 
 
 
-The `SwaggerService` generates link:http://swagger.io/[Swagger] spec files to describe the public and/or private RESTful APIs exposed by the xref:ugvro.adoc#[RestfulObjects viewer].
+The `SwaggerService` generates link:http://swagger.io/[Swagger] spec files to describe the public and/or private RESTful APIs exposed by the xref:../ugvro/ugvro.adoc#[RestfulObjects viewer].
 
 These spec files can then be used with the link:http://swagger.io/swagger-ui/[Swagger UI] page to explore the REST API, or used to generate client-side stubs using the link:http://swagger.io/swagger-codegen/[Swagger codegen] tool, eg for use in a custom REST client app.
 
 [NOTE]
 ====
-Not all of the REST API exposed by the xref:ugvro.adoc#[Restful Objects viewer] is included in the Swagger spec files; the emphasis is those REST resources that are used to develop custom apps: domain objects, domain object collections and action invocations.  When combined with Apache Isis' own xref:ugvro.adoc#_ugvro_simplified-representations[simplified representations], these are pretty much all that is needed  for this use case.
+Not all of the REST API exposed by the xref:../ugvro/ugvro.adoc#[Restful Objects viewer] is included in the Swagger spec files; the emphasis is those REST resources that are used to develop custom apps: domain objects, domain object collections and action invocations.  When combined with Apache Isis' own xref:../ugvro/ugvro.adoc#_ugvro_simplified-representations[simplified representations], these are pretty much all that is needed  for this use case.
 ====
 
 
@@ -38,7 +38,7 @@ public interface SwaggerService {
 }
 ----
 <1> Generate a Swagger spec for use by third-party clients, ie public use.  This specification is restricted only to
-xref:ugbtb.adoc#_ugbtb_view-models[view model]s and to domain services with a xref:../rgant/rgant.adoc#_rgant-DomainService_nature[nature] of `VIEW_REST_ONLY`.
+xref:../ugbtb/ugbtb.adoc#_ugbtb_view-models[view model]s and to domain services with a xref:../rgant/rgant.adoc#_rgant-DomainService_nature[nature] of `VIEW_REST_ONLY`.
 <2> Generate a Swagger spec for use only by internally-managed clients, ie private internal use.  This specification includes domain entities and all menu domain services (as well as any view models).
 <3> Generate a Swagger spec that is the same as private case (above), but also including any xref:../rgant/rgant.adoc#_rgant-Action_restrictTo[prototype] actions.
 <4> Swagger specs can be written either in JSON or YAML format.

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_SwitchUserService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_SwitchUserService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_SwitchUserService.adoc
index 60d6de6..f834f73 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_SwitchUserService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_SwitchUserService.adoc
@@ -13,7 +13,7 @@ different users of the system.
 
 [NOTE]
 ====
-This service is deprecated; use xref:ugtst.adoc#_ugtst_fixture-scripts[fixture scripts] and the
+This service is deprecated; use xref:../ugtst/ugtst.adoc#_ugtst_fixture-scripts[fixture scripts] and the
 xref:../rgsvc/rgsvc.adoc#_rgsvc_api_SudoService[`SudoService`] instead.
 ====
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_TransactionService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_TransactionService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_TransactionService.adoc
index 9dca04d..7fbc50b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_TransactionService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_TransactionService.adoc
@@ -35,7 +35,7 @@ xref:../rgsvc/rgsvc.adoc#_rgsvc_api_RepositoryService[`RepositoryService`]'s `pe
 framework actually queues up the work and only performs the persistence command either at the end of the transaction
 or immediately prior to the next query.  Performing a flush will cause any pending calls to be performed immediately.
 
-The `nextTransaction()` is also used by the xref:ugvw.adoc#[Wicket viewer]'s support for bulk actions; each action
+The `nextTransaction()` is also used by the xref:../ugvw/ugvw.adoc#[Wicket viewer]'s support for bulk actions; each action
 is invoked in its own transaction.
 
 The `Transaction` object - as obtained by `currentTransaction()` method, above - is a minimal wrapper around the

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_UserService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_UserService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_UserService.adoc
index bca048e..01e6267 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_UserService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_UserService.adoc
@@ -55,9 +55,9 @@ public final class RoleMemento {
 }
 ----
 
-The roles associated with the `UserMemento` will be based on the configured xref:ugsec.adoc#[security] (typically Shiro).
+The roles associated with the `UserMemento` will be based on the configured xref:../ugsec/ugsec.adoc#[security] (typically Shiro).
 
-In addition, when using the xref:ugvw.adoc#[Wicket viewer] there will be an additional "org.apache.isis.viewer.wicket.roles.USER" role; this is used internally to restrict access to web pages without authenticating.
+In addition, when using the xref:../ugvw/ugvw.adoc#[Wicket viewer] there will be an additional "org.apache.isis.viewer.wicket.roles.USER" role; this is used internally to restrict access to web pages without authenticating.
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_WrapperFactory.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_WrapperFactory.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_WrapperFactory.adoc
index 5eaa6b1..e633b0b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_WrapperFactory.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_WrapperFactory.adoc
@@ -13,12 +13,12 @@ For example, if the calling object attempts to modify an unmodifiable property o
 
 [NOTE]
 ====
-For a discussion of the use of the `WrapperFactory` within integration tests (the primary or at least original use case for this service) can be found xref:ugtst.adoc#_ugtst_integ-test-support_wrapper-factory[here]
+For a discussion of the use of the `WrapperFactory` within integration tests (the primary or at least original use case for this service) can be found xref:../ugtst/ugtst.adoc#_ugtst_integ-test-support_wrapper-factory[here]
 ====
 
 This capability goes beyond enforcing the (imperative) constraints within the `hideXxx()`, `disableXxx()` and `validateXxx()` supporting methods; it also enforces (declarative) constraints such as those represented by annotations, eg `@MaxLength` or `@Regex`.
 
-This capability is frequently used within xref:ugtst.adoc#_ugtst_integ-test-support[integration tests], but can also be used in production code. (There are analogies that can be drawn here with the way that JEE beans can interact through an EJB local interface).
+This capability is frequently used within xref:../ugtst/ugtst.adoc#_ugtst_integ-test-support[integration tests], but can also be used in production code. (There are analogies that can be drawn here with the way that JEE beans can interact through an EJB local interface).
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_application-layer-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_application-layer-api.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_application-layer-api.adoc
index 692cd3e..21a68c4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_application-layer-api.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_application-layer-api.adoc
@@ -27,7 +27,7 @@ The table below summarizes the application layer APIs defined by Apache Isis.  I
 |`AcceptHeaderServiceDefault` +
 ``o.a.i.core`` +
 ``isis-viewer-restfulobjects-rendering``
-|Populated only when the domain objects are accessed using the xref:ugvro.adoc#[Restful Objects viewer].
+|Populated only when the domain objects are accessed using the xref:../ugvro/ugvro.adoc#[Restful Objects viewer].
 
 
 |xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ActionInvocationContext[`o.a.i.applib.` +

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_intro.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_intro.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_intro.adoc
index 38fbc01..5351fec 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_intro.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_intro.adoc
@@ -19,8 +19,8 @@ image::{_imagesdir}reference-services/categories.png[width="600px",link="{_image
 
 
 A small number of domain services can be considered both API and SPI; a good example is the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EmailService[`EmailService`] that is of direct use for domain objects wishing to send out emails,
-but is also used by the framework to support the xref:ugvw.adoc#_ugvw_features_user-registration[user registration]
-functionality supported by the xref:ugvw.adoc#[Wicket viewer].   The same is true of the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`]; this can be used by domain objects to broadcast arbitrary events,
+but is also used by the framework to support the xref:../ugvw/ugvw.adoc#_ugvw_features_user-registration[user registration]
+functionality supported by the xref:../ugvw/ugvw.adoc#[Wicket viewer].   The same is true of the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`]; this can be used by domain objects to broadcast arbitrary events,
 but is also used by the framework to automatically emit events for
 xref:../rgant/rgant.adoc#_rgant-Action_domainEvent[`@Action#domainEvent()`] etc.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_metadata-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_metadata-api.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_metadata-api.adoc
index 3a3a52e..4c565f4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_metadata-api.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_metadata-api.adoc
@@ -70,7 +70,7 @@ within the metamodel.
 |xref:../rgsvc/rgsvc.adoc#_rgsvc_api_SwaggerService[`o.a.i.applib.` +
 `services.swagger` +
 `SwaggerService`]
-|Generates link:http://swagger.io/[Swagger] spec files to describe the public and/or private RESTful APIs exposed by the xref:ugvro.adoc#[RestfulObjects viewer].  These can then be used with the link:http://swagger.io/swagger-ui/[Swagger UI] page to explore the REST API, or used to generate client-side stubs using the link:http://swagger.io/swagger-codegen/[Swagger codegen] tool, eg for use in a custom REST client app.
+|Generates link:http://swagger.io/[Swagger] spec files to describe the public and/or private RESTful APIs exposed by the xref:../ugvro/ugvro.adoc#[RestfulObjects viewer].  These can then be used with the link:http://swagger.io/swagger-ui/[Swagger UI] page to explore the REST API, or used to generate client-side stubs using the link:http://swagger.io/swagger-codegen/[Swagger codegen] tool, eg for use in a custom REST client app.
 |`SwaggerServiceDefault` +
 ``o.a.i.core`` +
 ``isis-core-metamodel``

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_presentation-layer-spi.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_presentation-layer-spi.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_presentation-layer-spi.adoc
index 6c0ed69..dd72df4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_presentation-layer-spi.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_presentation-layer-spi.adoc
@@ -126,7 +126,7 @@ grids for any domain class.
 ``o.a.i.core`` +
 ``isis-core-applib``
 |The default implementation will return the home page (per xref:../rgsvc/rgsvc.adoc#_rgsvc_api_HomePageProviderService[`HomePageProviderService`]) if a void or null is returned. +
-Used by the xref:ugvw.adoc#[Wicket viewer] only.
+Used by the xref:../ugvw/ugvw.adoc#[Wicket viewer] only.
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_AuditerService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_AuditerService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_AuditerService.adoc
index e0f435d..85e0ec7 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_AuditerService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_AuditerService.adoc
@@ -109,7 +109,7 @@ Assuming that an `AppManifest` is being used to xref:../rgcms/rgcms.adoc#_rgcms_
 then this can be activated by updating the `pom.xml` and updating the `AppManifest#getModules()` method.
 
 If menu items or contributions are not required in the UI, these can be suppressed either using security or by
-implementing a xref:ugbtb.adoc#_ugbtb_decoupling_vetoing-visibility[vetoing subscriber].
+implementing a xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_vetoing-visibility[vetoing subscriber].
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_AuditingService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_AuditingService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_AuditingService.adoc
index 63ed0f8..062c87e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_AuditingService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_AuditingService.adoc
@@ -71,7 +71,7 @@ Assuming that an `AppManifest` is being used to xref:../rgcms/rgcms.adoc#_rgcms_
 then this can be activated by updating the `pom.xml` and updating the `AppManifest#getModules()` method.
 
 If menu items or contributions are not required in the UI, these can be suppressed either using security or by
-implementing a xref:ugbtb.adoc#_ugbtb_decoupling_vetoing-visibility[vetoing subscriber].
+implementing a xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_vetoing-visibility[vetoing subscriber].
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_BackgroundCommandService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_BackgroundCommandService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_BackgroundCommandService.adoc
index 57ae70e..7040283 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_BackgroundCommandService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_BackgroundCommandService.adoc
@@ -56,7 +56,7 @@ public class ActionInvocationMemento {
 
 == "Internal" SPI
 
-The `BackgroundCommandExecution` (in isis-core) is an abstract template class for  xref:ugbtb.adoc#_ugbtb_headless-access_AbstractIsisSessionTemplate[headless access], that defines an abstract hook method to obtain background `Command`s to be executed:
+The `BackgroundCommandExecution` (in isis-core) is an abstract template class for  xref:../ugbtb/ugbtb.adoc#_ugbtb_headless-access_AbstractIsisSessionTemplate[headless access], that defines an abstract hook method to obtain background `Command`s to be executed:
 
 [source,java]
 ----
@@ -114,7 +114,7 @@ Assuming that an `AppManifest` is being used to xref:../rgcms/rgcms.adoc#_rgcms_
 then this can be activated by updating the `pom.xml` and updating the `AppManifest#getModules()` method.
 
 If contributions are not required in the UI, these can be suppressed either using security or by implementing a
-xref:ugbtb.adoc#_ugbtb_decoupling_vetoing-visibility[vetoing subscriber].
+xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_vetoing-visibility[vetoing subscriber].
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_CommandService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_CommandService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_CommandService.adoc
index f211af1..d0dcb05 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_CommandService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_CommandService.adoc
@@ -40,7 +40,7 @@ The link:https://www.youtube.com/watch?v=tqXUZkPB3EI[screencast] below provides
 
 [NOTE]
 ====
-Note that this screencast shows an earlier version of the xref:ugvw.adoc#[Wicket viewer] UI (specifically, pre 1.8.0).
+Note that this screencast shows an earlier version of the xref:../ugvw/ugvw.adoc#[Wicket viewer] UI (specifically, pre 1.8.0).
 ====
 
 
@@ -101,7 +101,7 @@ Assuming that an `AppManifest` is being used to xref:../rgcms/rgcms.adoc#_rgcms_
 then this can be activated by updating the `pom.xml` and updating the `AppManifest#getModules()` method.
 
 If contributions are not required in the UI, these can be suppressed either using security or by implementing a
-xref:ugbtb.adoc#_ugbtb_decoupling_vetoing-visibility[vetoing subscriber].
+xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_vetoing-visibility[vetoing subscriber].
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_ContentMappingService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_ContentMappingService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_ContentMappingService.adoc
index bb21807..b06c46b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_ContentMappingService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_ContentMappingService.adoc
@@ -8,7 +8,7 @@
 
 The `ContentMappingService` supports the (default implementation of the)
 xref:../rgfis/rgfis.adoc#_rgfis_spi_ContentNegotiationService[`ContentNegotiationService`] allowing the
-xref:ugvro.adoc#[RestfulObjects viewer] to allow domain objects to be transformed into some other format as specified
+xref:../ugvro/ugvro.adoc#[RestfulObjects viewer] to allow domain objects to be transformed into some other format as specified
 by the HTTP `Accept` header.
 
 See xref:../rgfis/rgfis.adoc#_rgfis_spi_ContentNegotiationService[`ContentNegotiationService`] for further discussion.
@@ -42,7 +42,7 @@ public interface ContentMappingService {
 
 
 In versions prior to `v1.12.0`, this interface resided in a different package, internal to the
-xref:ugvro.adoc[Restful Objects] viewer, and defined a slightly different signature that used an internal enum:
+xref:../ugvro/ugvro.adoc[Restful Objects] viewer, and defined a slightly different signature that used an internal enum:
 
 [source,java]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_EmailNotificationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_EmailNotificationService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_EmailNotificationService.adoc
index 1bab3a1..03aa19d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_EmailNotificationService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_EmailNotificationService.adoc
@@ -6,7 +6,7 @@
 
 
 
-The `EmailNotificationService` supports the xref:ugvw.adoc#_ugvw_features_user-registration[user registration] (self sign-up) features of the xref:ugvw.adoc#[Wicket viewer] whereby a user can sign-up to access an application by providing a valid email address.
+The `EmailNotificationService` supports the xref:../ugvw/ugvw.adoc#_ugvw_features_user-registration[user registration] (self sign-up) features of the xref:../ugvw/ugvw.adoc#[Wicket viewer] whereby a user can sign-up to access an application by providing a valid email address.
 
 The Wicket viewer will check whether an implementation of this service (and also the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UserRegistrationService[`UserRegistrationService`]) is available, and if so will (unless configured not to) expose a sign-up page where the user enters their email address. A verification email is sent using this service; the email includes a link back to the running application. The user then completes the registration process (choosing a user name, password and so on) and the Wicket viewer creates an account for them (using the aforementioned `UserRegistrationService`).
 
@@ -50,7 +50,7 @@ The text of these email templates is hard-coded as resources, in other words bak
 
 If you have configured an alternative email service implementation, it should process the message body as HTML.
 
-If you wish to write an alternative implementation of this service, note that (unlike most Apache Isis domain services) the implementation is also instantiated and injected by Google Guice. This is because `EmailNotificationService` is used as part of the xref:ugvw.adoc#_ugvw_features_user-registration[user registration] functionality and is used by Wicket pages that are accessed outside of the usual Apache Isis runtime.
+If you wish to write an alternative implementation of this service, note that (unlike most Apache Isis domain services) the implementation is also instantiated and injected by Google Guice. This is because `EmailNotificationService` is used as part of the xref:../ugvw/ugvw.adoc#_ugvw_features_user-registration[user registration] functionality and is used by Wicket pages that are accessed outside of the usual Apache Isis runtime.
 
 This implies a couple of additional constraints:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_ExceptionRecognizer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_ExceptionRecognizer.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_ExceptionRecognizer.adoc
index 85db100..af737f5 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_ExceptionRecognizer.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_ExceptionRecognizer.adoc
@@ -69,7 +69,7 @@ public interface ExceptionRecognizer2 ... {
 <6> recognized, but uncategorized (typically: a recognizer of the original `ExceptionRecognizer` API).
 
 
-In essence, if an exception is recognized then it is also categorized.  This lets the viewer act accordingly.  For example, if an exception is raised from the loading of an individual object, then this is passed by the registered ``ExceptionRecognizer``s. If any of these recognize the exception as representing a not-found exception, then an Apache Isis `ObjectNotFoundException` is raised. Both the viewers interprets this correctly (the xref:ugvw.adoc#[Wicket viewer] as a suitable error page, the xref:ugvro.adoc#[Restful Objects viewer] as a 404 status return code).
+In essence, if an exception is recognized then it is also categorized.  This lets the viewer act accordingly.  For example, if an exception is raised from the loading of an individual object, then this is passed by the registered ``ExceptionRecognizer``s. If any of these recognize the exception as representing a not-found exception, then an Apache Isis `ObjectNotFoundException` is raised. Both the viewers interprets this correctly (the xref:../ugvw/ugvw.adoc#[Wicket viewer] as a suitable error page, the xref:../ugvro/ugvro.adoc#[Restful Objects viewer] as a 404 status return code).
 
 
 If the implementation recognizes the exception then it returns a user-friendly message to be rendered (by the viewer) back to the user; otherwise it returns `null`. There is no need for the implementation to check for exception causes; the casual chain is unwrapped by Apache Isis core and each exception in the chain will also be passed through to the recognizer (from most specific to least). The recognizer implementation can therefore be as fine-grained or as coarse-grained as it wishes.

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_GridSystemService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_GridSystemService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_GridSystemService.adoc
index d610cee..523bea6 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_GridSystemService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_GridSystemService.adoc
@@ -55,7 +55,7 @@ the service with the lowest xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_
 == Implementation
 
 The framework provides `GridSystemServiceBS3`, an implementation that encodes the bootstrap3 grid system.  (The framework
-also provides xref:ugvw.adoc[Wicket viewer] components that are capable of interpreting and rendering this metadata).
+also provides xref:../ugvw/ugvw.adoc[Wicket viewer] components that are capable of interpreting and rendering this metadata).
 
 
 == Registering the Services

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_HintStore.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_HintStore.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_HintStore.adoc
index 34bfcca..6d172d2 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_HintStore.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_HintStore.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-The `HintStore` service defines an SPI for the xref:ugvw.adoc#[Wicket viewer] to store UI hints on a per-object basis.
+The `HintStore` service defines an SPI for the xref:../ugvw/ugvw.adoc#[Wicket viewer] to store UI hints on a per-object basis.
 For example, the viewer remembers which tabs are selected, and for collections which view is selected (eg table or hidden),
 which page of a table to render, or whether "show all" (rows) is toggled.
 
@@ -59,6 +59,6 @@ in the xref:../rgsvc/rgsvc.adoc#__rgsvc_intro_overriding-the-services[introducti
 
 == Related Services
 
-The xref:ugvw.adoc[Wicket viewer] exposes the xref:../rgcms/rgcms.adoc#__rgcms_classes_mixins_Object_clearHints["clear hints"]
+The xref:../ugvw/ugvw.adoc[Wicket viewer] exposes the xref:../rgcms/rgcms.adoc#__rgcms_classes_mixins_Object_clearHints["clear hints"]
 mixin action that is for use by end-users of the application to clear any UI hints that have accumulated for a
 domain object.

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_LocaleProvider.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_LocaleProvider.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_LocaleProvider.adoc
index a31b079..2167d64 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_LocaleProvider.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_LocaleProvider.adoc
@@ -13,7 +13,7 @@ The role of the service itself is simply to return the `Locale` of the current u
 
 [NOTE]
 ====
-For the "big picture" and further details on Apache Isis' i18n support, see xref:ugbtb.adoc#_ugbtb_i18n[here].
+For the "big picture" and further details on Apache Isis' i18n support, see xref:../ugbtb/ugbtb.adoc#_ugbtb_i18n[here].
 ====
 
 
@@ -37,11 +37,11 @@ This is notionally request-scoped, returning the `Locale` of the current user; _
 
 == Implementation
 
-Isis' xref:ugvw.adoc#[Wicket viewer] provides an implementation of this service (`LocaleProviderWicket`) which leverages Apache Wicket APIs.
+Isis' xref:../ugvw/ugvw.adoc#[Wicket viewer] provides an implementation of this service (`LocaleProviderWicket`) which leverages Apache Wicket APIs.
 
 [NOTE]
 ====
-Currently there is no equivalent implementation for the xref:ugvro.adoc#[RestfulObjects viewer].
+Currently there is no equivalent implementation for the xref:../ugvro/ugvro.adoc#[RestfulObjects viewer].
 ====
 
 
@@ -51,7 +51,7 @@ Currently there is no equivalent implementation for the xref:ugvro.adoc#[Restful
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
 `AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]), __and__ that the
-xref:ugvw.adoc#[Wicket viewer] is being used, then an implementation of `LocaleProvider` is
+xref:../ugvw/ugvw.adoc#[Wicket viewer] is being used, then an implementation of `LocaleProvider` is
 automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
 
 To use an alternative implementation, use

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_PublisherService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_PublisherService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_PublisherService.adoc
index fa65e0e..192638f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_PublisherService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_PublisherService.adoc
@@ -120,7 +120,7 @@ the `pom.xml` and updating the `AppManifest#getModules()` method.
 
 The module also provide services that contribute to the UI.  If contributions are not required in the UI, these can be
 suppressed either using security or by implementing a
-xref:ugbtb.adoc#_ugbtb_decoupling_vetoing-visibility[vetoing subscriber].
+xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_vetoing-visibility[vetoing subscriber].
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_PublishingService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_PublishingService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_PublishingService.adoc
index 7897e4f..f64091a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_PublishingService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_PublishingService.adoc
@@ -160,7 +160,7 @@ the `pom.xml` and updating the `AppManifest#getModules()` method.
 
 The module also provides services that contribute to the UI.  If contributions are not required in the UI, these can be
 suppressed either using security or by implementing a
-xref:ugbtb.adoc#_ugbtb_decoupling_vetoing-visibility[vetoing subscriber].
+xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_vetoing-visibility[vetoing subscriber].
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_RoutingService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_RoutingService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_RoutingService.adoc
index 899f379..6876445 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_RoutingService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_RoutingService.adoc
@@ -20,7 +20,7 @@ of the implementation to figure out what the "owning" object might be.
 +
 For example, return the home page (eg as defined by the xref:../rgant/rgant.adoc#_rgant-HomePage[`@HomePage`] annotation).
 
-Currently the routing service is used only by the xref:ugvw.adoc#[Wicket viewer]; it is ignored by the xref:ugvro.adoc#[Restful Objects] viewer.
+Currently the routing service is used only by the xref:../ugvw/ugvw.adoc#[Wicket viewer]; it is ignored by the xref:../ugvro/ugvro.adoc#[Restful Objects] viewer.
 
 
 [NOTE]

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_TranslationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_TranslationService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_TranslationService.adoc
index 451163c..16a713e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_TranslationService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_TranslationService.adoc
@@ -11,7 +11,7 @@ The `TranslationService` is the cornerstone of Apache Isis' i18n support.  Its r
 
 [NOTE]
 ====
-For the "big picture" and further details on Apache Isis' i18n support, see xref:ugbtb.adoc#_ugbtb_i18n[here].
+For the "big picture" and further details on Apache Isis' i18n support, see xref:../ugbtb/ugbtb.adoc#_ugbtb_i18n[here].
 ====
 
 
@@ -53,7 +53,7 @@ The Apache Isis framework provides a default implementation (`TranslationService
 
 The framework also provides a supporting `TranslationServicePoMenu` provides menu items under the "Prototyping" secondary menu for controlling this service and downloading `.pot` files for translation.
 
-For more details on the implementation, see xref:ugbtb.adoc#_ugbtb_i18n[i18n support].
+For more details on the implementation, see xref:../ugbtb/ugbtb.adoc#_ugbtb_i18n[i18n support].
 
 
 
@@ -64,7 +64,7 @@ Assuming that the `configuration-and-annotation` services installer is configure
 `AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
 implementation of `TranslationService` service (along with the supporting menu service) are automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
 
-If the menu items are not required then these can be suppressed either using security or by implementing a xref:ugbtb.adoc#_ugbtb_decoupling_vetoing-visibility[vetoing subscriber].
+If the menu items are not required then these can be suppressed either using security or by implementing a xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_vetoing-visibility[vetoing subscriber].
 
 To use an alternative implementation, use
 xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_TranslationsResolver.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_TranslationsResolver.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_TranslationsResolver.adoc
index 2c14678..7c55660 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_TranslationsResolver.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_TranslationsResolver.adoc
@@ -13,7 +13,7 @@ The role of the service itself is locate and return translations.
 
 [NOTE]
 ====
-For the "big picture" and further details on Apache Isis' i18n support, see xref:ugbtb.adoc#_ugbtb_i18n[here].
+For the "big picture" and further details on Apache Isis' i18n support, see xref:../ugbtb/ugbtb.adoc#_ugbtb_i18n[here].
 ====
 
 
@@ -33,11 +33,11 @@ public interface TranslationsResolver {
 
 == Implementation
 
-Isis' xref:ugvw.adoc#[Wicket viewer] provides an implementation of this service (`TranslationsResolverWicket`) which leverages Apache Wicket APIs.  This searches for translation files in the standard `WEB-INF/` directory.
+Isis' xref:../ugvw/ugvw.adoc#[Wicket viewer] provides an implementation of this service (`TranslationsResolverWicket`) which leverages Apache Wicket APIs.  This searches for translation files in the standard `WEB-INF/` directory.
 
 [NOTE]
 ====
-Currently there is no equivalent implementation for the xref:ugvro.adoc#[RestfulObjects viewer].
+Currently there is no equivalent implementation for the xref:../ugvro/ugvro.adoc#[RestfulObjects viewer].
 ====
 
 
@@ -47,7 +47,7 @@ Currently there is no equivalent implementation for the xref:ugvro.adoc#[Restful
 == Registering the Service
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]), _and_ that the xref:ugvw.adoc#[Wicket viewer] is being used, then an implementation of `TranslationsResolver` is
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]), _and_ that the xref:../ugvw/ugvw.adoc#[Wicket viewer] is being used, then an implementation of `TranslationsResolver` is
 automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
 
 To use an alternative implementation, use

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_UrlEncodingService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_UrlEncodingService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_UrlEncodingService.adoc
index 1f5efbc..05f948c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_UrlEncodingService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_UrlEncodingService.adoc
@@ -7,7 +7,7 @@
 
 
 The `UrlEncodingService` defines a consistent way to convert strings to/from a form safe for use
-within a URL.  The service is used by the framework to map xref:ugbtb.adoc#_ugbtb_view-models[view model]
+within a URL.  The service is used by the framework to map xref:../ugbtb/ugbtb.adoc#_ugbtb_view-models[view model]
 mementos (derived from the state of the view model itself) into a form that can be used as a view model.  When the
 framework needs to recreate the view model (for example to invoke an action on it), this URL is converted back into a
 view model memento, from which the view model can then be hydrated.

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_UserProfileService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_UserProfileService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_UserProfileService.adoc
index 9b1add5..67188bd 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_UserProfileService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_UserProfileService.adoc
@@ -6,7 +6,7 @@
 
 
 
-The `UserProfileService` provides the ability for the domain application to return supplementary metadata about the current user. This information is used (by the xref:ugvw.adoc#[Wicket viewer]) to customize the appearance of the tertiary "Me" menu bar (top right). For example, rather than display the username, instead the user's first and last name could be displayed.
+The `UserProfileService` provides the ability for the domain application to return supplementary metadata about the current user. This information is used (by the xref:../ugvw/ugvw.adoc#[Wicket viewer]) to customize the appearance of the tertiary "Me" menu bar (top right). For example, rather than display the username, instead the user's first and last name could be displayed.
 
 Another use case is to allow the user to switch context in some fashion or other. This might be to emulate a sort of "sudo"-like function, or perhaps to focus on some particular set of data.
 

[17/58] [abbrv] isis git commit: ISIS-1521: more reorganizing of images and also resources for dg.adoc

[da...@apache.org]

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/resources/appendices/dev-env/eclipse/isis-templates.xml
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/resources/appendices/dev-env/eclipse/isis-templates.xml b/adocs/documentation/src/main/asciidoc/guides/dg/resources/appendices/dev-env/eclipse/isis-templates.xml
deleted file mode 100644
index f8ea500..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/dg/resources/appendices/dev-env/eclipse/isis-templates.xml
+++ /dev/null
@@ -1,465 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
-  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.
--->
-<templates><template autoinsert="true" context="java-members" deleted="false" description="Action" enabled="true" name="isa">// {{ ${actionName} (action)&#13;
-${:import(org.apache.isis.applib.annotation.MemberOrder)}@MemberOrder(sequence="1")&#13;
-public ${ReturnType} ${actionName}(final ${ParameterType} ${parameterType}) {&#13;
-	return ${cursor}null; // TODO: business logic here&#13;
-}&#13;
-// }}&#13;
-&#13;
-</template><template autoinsert="true" context="java-members" deleted="false" description="Action argument N choices" enabled="true" name="isacho">${:import(java.util.Collections,java.util.List)}public List&lt;${ParameterType}&gt; choices${ParameterNumThenCapitalizedActionName}() {&#13;
-	return ${cursor}Collections.emptyList(); // TODO: return list of choices for argument N&#13;
-}</template><template autoinsert="true" context="java-members" deleted="false" description="Action argument defaults" enabled="true" name="isadef">public ${ParameterType} default${ParameterNumThenCapitalizedActionName}() {&#13;
-	return ${cursor}null; // TODO: return default for argument N&#13;
-}</template><template autoinsert="true" context="java-members" deleted="false" description="Action disabling" enabled="true" name="isadis">public String disable${ActionName}() {&#13;
-	return ${cursor}null; // TODO: return reason why action disabled, null if enabled&#13;
-}</template><template autoinsert="true" context="java-members" deleted="false" description="Action hiding" enabled="true" name="isahid">public boolean hide${ActionName}() {&#13;
-	return ${cursor}false; // TODO: return true if action is hidden, false if visible&#13;
-}</template><template autoinsert="true" context="java-members" deleted="false" description="Action validation" enabled="true" name="isaval">public String validate${ActionName}(final ${ParameterType} ${parameterType}) {&#13;
-	return ${cursor}null; // TODO: return reason why action arguments are invalid, null if ok&#13;
-}</template><template autoinsert="true" context="java-members" deleted="false" description="Collection (1:m bidir parent)" enabled="true" name="isc-1m">public void addTo${ChildCollectionName}(final ${ChildElementType} ${childElementName}) {&#13;
-	// check for no-op&#13;
-	if (${childElementName} == null || &#13;
-		get${ChildCollectionName}().contains(${childElementName})) {&#13;
-		return;&#13;
-	}&#13;
-	// dissociate arg from its current parent (if any).&#13;
-	${childElementName}.clear${ParentPropertyNameInChild}();&#13;
-	// associate arg&#13;
-	${childElementName}.set${ParentPropertyNameInChild}(this);&#13;
-	get${ChildCollectionName}().add(${childElementName});&#13;
-	// additional business logic&#13;
-	onAddTo${ChildCollectionName}(${childElementName});&#13;
-}&#13;
-public void removeFrom${ChildCollectionName}(final ${ChildElementType} ${childElementName}) {&#13;
-	// check for no-op&#13;
-	if (${childElementName} == null || &#13;
-		!get${ChildCollectionName}().contains(${childElementName})) {&#13;
-		return;&#13;
-	}&#13;
-	// dissociate arg&#13;
-	${childElementName}.set${ParentPropertyNameInChild}(null);&#13;
-	get${ChildCollectionName}().remove(${childElementName});&#13;
-	// additional business logic&#13;
-	onRemoveFrom${ChildCollectionName}(${childElementName});&#13;
-}</template><template autoinsert="true" context="java-members" deleted="false" description="Collection (m:m bidir child)" enabled="true" name="isc-mmc">public void addTo${ParentCollectionName}(final ${ParentElementType} ${parentElementName}) {&#13;
-	// check for no-op&#13;
-	if (${parentElementName} == null || &#13;
-		get${ParentCollectionName}().contains(${parentElementName})) {&#13;
-		return;&#13;
-	}&#13;
-	// delegate to parent to add&#13;
-	${parentElementName}.addTo${ChildCollectionNameInParent}(this);&#13;
-	// additional business logic&#13;
-	onAddTo${ParentCollectionName}(${parentElementName});&#13;
-}&#13;
-public void removeFrom${ParentCollectionName}(final ${ParentElementType} ${parentElementName}) {&#13;
-	// check for no-op&#13;
-	if (${parentElementName} == null || &#13;
-		!get${ParentCollectionName}().contains(${parentElementName})) {&#13;
-		return;&#13;
-	}&#13;
-	// delegate to parent to remove&#13;
-	${parentElementName}.removeFrom${ChildCollectionNameInParent}(this);&#13;
-	// additional business logic&#13;
-	onRemoveFrom${ParentCollectionName}(${parentElementName});&#13;
-}</template><template autoinsert="true" context="java-members" deleted="false" description="Collection (m:m bidir parent)" enabled="true" name="isc-mmp">public void addTo${ChildCollectionName}(final ${ChildElementType} ${childElementName}) {&#13;
-	// check for no-op&#13;
-	if (${childElementName} == null || &#13;
-		get${ChildCollectionName}().contains(${childElementName})) {&#13;
-		return;&#13;
-	}&#13;
-	// dissociate arg from its current parent (if any).&#13;
-	${childElementName}.removeFrom${ParentCollectionNameInChild}(this);&#13;
-	// associate arg&#13;
-	${childElementName}.get${ParentCollectionNameInChild}().add(this);&#13;
-	get${ChildCollectionName}().add(${childElementName});&#13;
-	// additional business logic&#13;
-	onAddTo${ChildCollectionName}(${childElementName});&#13;
-}&#13;
-public void removeFrom${ChildCollectionName}(final ${ChildElementType} ${childElementName}) {&#13;
-	// check for no-op&#13;
-	if (${childElementName} == null || &#13;
-		!get${ChildCollectionName}().contains(${childElementName})) {&#13;
-		return;&#13;
-	}&#13;
-	// dissociate arg&#13;
-	${childElementName}.get${ParentCollectionNameInChild}().remove(this);&#13;
-	get${ChildCollectionName}().remove(${childElementName});&#13;
-	// additional business logic&#13;
-	onRemoveFrom${ChildCollectionName}(${childElementName});&#13;
-}</template><template autoinsert="true" context="java-members" deleted="false" description="Collection disabling" enabled="true" name="iscdis">public String disable${CollectionName}() {&#13;
-	return ${cursor}null; // TODO: return reason why collection read-only, null if editable&#13;
-}</template><template autoinsert="true" context="java-members" deleted="false" description="Collection hiding" enabled="true" name="ischid">public boolean hide${CollectionName}() {&#13;
-	return ${cursor}false; // TODO: return true if hidden, false otherwise&#13;
-}</template><template autoinsert="true" context="java-members" deleted="false" description="Collection (list)" enabled="true" name="iscl">// {{ ${CollectionName} (Collection)&#13;
-${:import(java.util.List,java.util.ArrayList,org.apache.isis.applib.annotation.MemberOrder)}private List&lt;${ElementType}&gt; ${collectionName} = new ArrayList&lt;${ElementType}&gt;();&#13;
-@MemberOrder(sequence="1")&#13;
-public List&lt;${ElementType}&gt; get${CollectionName}() {&#13;
-	return ${collectionName};&#13;
-}&#13;
-public void set${CollectionName}(final List&lt;${ElementType}&gt; ${collectionName}) {&#13;
-	this.${collectionName} = ${collectionName};&#13;
-}&#13;
-// }}&#13;
-&#13;
-</template><template autoinsert="true" context="java-members" deleted="false" description="Collection modify" enabled="true" name="iscmod">public void addTo${CollectionName}(final ${ElementType} ${elementName}) {&#13;
-	// check for no-op&#13;
-	if (${elementName} == null || &#13;
-		get${CollectionName}().contains(${elementName})) {&#13;
-		return;&#13;
-	}&#13;
-	// associate new&#13;
-	get${CollectionName}().add(${elementName});&#13;
-    // additional business logic&#13;
-    onAddTo${CollectionName}(${elementName});&#13;
-}&#13;
-public void removeFrom${CollectionName}(final ${ElementType} ${elementName}) {&#13;
-	// check for no-op&#13;
-	if (${elementName} == null || &#13;
-		!get${CollectionName}().contains(${elementName})) {&#13;
-		return;&#13;
-	}&#13;
-	// dissociate existing&#13;
-	get${CollectionName}().remove(${elementName});&#13;
-    // additional business logic&#13;
-    onRemoveFrom${CollectionName}(${elementName});&#13;
-}&#13;
-protected void onAddTo${CollectionName}(final ${ElementType} ${elementName}) {&#13;
-}&#13;
-protected void onRemoveFrom${CollectionName}(final ${ElementType} ${elementName}) {&#13;
-}</template><template autoinsert="true" context="java-members" deleted="false" description="Collection (set)" enabled="true" name="iscs">// {{ ${CollectionName} (Collection)&#13;
-${:import(java.util.Set,java.util.LinkedHashSet,org.apache.isis.applib.annotation.MemberOrder)}private Set&lt;${ElementType}&gt; ${collectionName} = new LinkedHashSet&lt;${ElementType}&gt;();&#13;
-@MemberOrder(sequence="1")&#13;
-public Set&lt;${ElementType}&gt; get${CollectionName}() {&#13;
-	return ${collectionName};&#13;
-}&#13;
-public void set${CollectionName}(final Set&lt;${ElementType}&gt; ${collectionName}) {&#13;
-	this.${collectionName} = ${collectionName};&#13;
-}&#13;
-// }}&#13;
-&#13;
-</template><template autoinsert="true" context="java-members" deleted="false" description="Collection validation" enabled="true" name="iscval">public String validateAddTo${CollectionName}(final ${ElementType} ${elementName}) {&#13;
-	return ${cursor}null; // TODO: return reason why argument cannot be added, null if ok to add&#13;
-}&#13;
-public String validateRemoveFrom${CollectionName}(final ${ElementType} ${elementName}) {&#13;
-	return null; // TODO: return reason why argument cannot be removed, null if ok to remove&#13;
-}&#13;
-&#13;
-</template><template autoinsert="true" context="java-members" deleted="false" description="Dependencies region" enabled="true" name="isd">// {{ injected dependencies&#13;
-${cursor}&#13;
-// }}&#13;
-&#13;
-</template><template autoinsert="true" context="java-members" deleted="false" description="Dependencies - injected service" enabled="true" name="isds">// {{ injected: ${ServiceType}&#13;
-private ${ServiceType} ${serviceType};&#13;
-public void set${ServiceType}(final ${ServiceType} ${serviceType}) {&#13;
-	this.${serviceType} = ${serviceType};&#13;
-}&#13;
-// }}&#13;
-&#13;
-</template><template autoinsert="true" context="java-members" deleted="false" description="Factory - new instance (persistent)" enabled="true" name="isfp">// {{ Create new (already persisted) ${Type}&#13;
-public ${Type} new${Type}() {&#13;
-	${Type} ${type} = newTransientInstance(${Type}.class);&#13;
-	${cursor}// TODO: set up any properties&#13;
-&#13;
-	persist(${type});&#13;
-	return ${type};&#13;
-}&#13;
-// }}</template><template autoinsert="true" context="java-members" deleted="false" description="Factory - new instance (transient)" enabled="true" name="isft">// {{ Create new (still transient) ${Type}&#13;
-public ${Type} new${InstanceOfType}() {&#13;
-	${Type} ${type} = newTransientInstance(${Type}.class);&#13;
-	${cursor}// TODO: set up any properties&#13;
-&#13;
-	return ${type};&#13;
-}&#13;
-// }}</template><template autoinsert="true" context="java-members" deleted="false" description="Identification region" enabled="true" name="isid">// {{ Identification&#13;
-${cursor}&#13;
-// }}&#13;
-&#13;
-</template><template autoinsert="true" context="java-members" deleted="false" description="Identification - icon" enabled="true" name="isidicon">public String iconName() {&#13;
-	return ${cursor}null; // TODO: return name of image file (without suffix)&#13;
-}</template><template autoinsert="true" context="java-members" deleted="false" description="Identification - title" enabled="true" name="isidtitle">public String title() {&#13;
-    ${:import(org.apache.isis.applib.util.TitleBuffer)}final TitleBuffer buf = new TitleBuffer();&#13;
-    ${cursor}// TODO: append to TitleBuffer, typically value properties&#13;
-	return buf.toString();&#13;
-}</template><template autoinsert="true" context="java-members" deleted="false" description="JDO Collection (1:n bidir, foreign key)" enabled="true" name="isjdc-1n-b-fk">// {{ ${CollectionName} (Collection)
-${:import(java.util.SortedSet,java.util.TreeSet,org.apache.isis.applib.annotation.MemberOrder,javax.jdo.annotations.Persistent)}@Persistent(mappedBy="${elementNameInChild}", dependentElement="${trueOrFalse}")
-private SortedSet&lt;${ElementType}&gt; ${collectionName} = new TreeSet&lt;${ElementType}&gt;();
-@MemberOrder(sequence="1")
-public SortedSet&lt;${ElementType}&gt; get${CollectionName}() {
-return ${collectionName};
-}
-public void set${CollectionName}(final SortedSet&lt;${ElementType}&gt; ${collectionName}) {
-this.${collectionName} = ${collectionName};
-}
-// }}</template><template autoinsert="true" context="java-members" deleted="false" description="JDO Collection (1:n bidir, join table)" enabled="true" name="isjdc-1n-b-jt">// {{ ${CollectionName} (Collection)
-${:import(java.util.SortedSet,java.util.TreeSet,org.apache.isis.applib.annotation.MemberOrder,javax.jdo.annotations.Persitent,javax.jdo.annotations.Join)}@Persistent(mappedBy="${elementNameInChild}", dependentElement="${trueOrFalse}")
-@Join
-private SortedSet&lt;${ElementType}&gt; ${collectionName} = new TreeSet&lt;${ElementType}&gt;();
-@MemberOrder(sequence="1")
-public SortedSet&lt;${ElementType}&gt; get${CollectionName}() {
-return ${collectionName};
-}
-public void set${CollectionName}(final SortedSet&lt;${ElementType}&gt; ${collectionName}) {
-this.${collectionName} = ${collectionName};
-}
-// }}</template><template autoinsert="true" context="java-members" deleted="false" description="JDO Collection (1:n unidir, foreign key)" enabled="true" name="isjdc-1n-u-fk">// {{ ${CollectionName} (Collection)
-${:import(java.util.SortedSet,java.util.TreeSet,org.apache.isis.applib.annotation.MemberOrder,javax.jdo.annotations.Element)}
-@Element(column="${ColumnName}", dependent="${trueOrFalse}")
-private SortedSet&lt;${ElementType}&gt; ${collectionName} = new TreeSet&lt;${ElementType}&gt;();
-@MemberOrder(sequence="1")
-public SortedSet&lt;${ElementType}&gt; get${CollectionName}() {
-return ${collectionName};
-}
-public void set${CollectionName}(final SortedSet&lt;${ElementType}&gt; ${collectionName}) {
-this.${collectionName} = ${collectionName};
-}
-// }}</template><template autoinsert="true" context="java-members" deleted="false" description="JDO Collection (1:n unidir, join table)" enabled="true" name="isjdc-1n-u-jt">// {{ ${CollectionName} (Collection)
-${:import(java.util.SortedSet,java.util.TreeSet,org.apache.isis.applib.annotation.MemberOrder,javax.jdo.annotations.Join,javax.jdo.annotations.Element)}@Join
-@Element(dependent="${trueOrFalse}")
-private SortedSet&lt;${ElementType}&gt; ${collectionName} = new TreeSet&lt;${ElementType}&gt;();
-@MemberOrder(sequence="1")
-public SortedSet&lt;${ElementType}&gt; get${CollectionName}() {
-return ${collectionName};
-}
-public void set${CollectionName}(final SortedSet&lt;${ElementType}&gt; ${collectionName}) {
-this.${collectionName} = ${collectionName};
-}
-// }}</template><template autoinsert="true" context="java-members" deleted="false" description="JDO Collection (m:n bidir - child)" enabled="true" name="isjdc-mn-ub-c">// {{ ${CollectionName} (Collection)
-${:import(java.util.SortedSet,java.util.TreeSet,org.apache.isis.applib.annotation.MemberOrder,javax.jdo.annotations.Persistent)}@Persistent(mappedBy="${ChildCollectionNameInParent}")
-private SortedSet&lt;${ElementType}&gt; ${collectionName} = new TreeSet&lt;${ElementType}&gt;();
-public SortedSet&lt;${ElementType}&gt; get${CollectionName}() {
-return ${collectionName};
-}
-public void set${CollectionName}(final SortedSet&lt;${ElementType}&gt; ${collectionName}) {
-this.${collectionName} = ${collectionName};
-}
-// }}</template><template autoinsert="true" context="java-members" deleted="false" description="JDO Collection (m:n unidir &amp; bidir - parent)" enabled="true" name="isjdc-mn-ub-p">// {{ ${CollectionName} (Collection)
-${:import(java.util.SortedSet,java.util.TreeSet,org.apache.isis.applib.annotation.MemberOrder,javax.jdo.annotations.Persistent,javax.jdo.annotations.Join,javax.jdo.annotations.Element)}@Persistent(table="${TableName}")
-@Join(column="${ThisEntityFieldName}")
-@Element(column="${RelatedEntityFieldName}")
-private SortedSet&lt;${ElementType}&gt; ${collectionName} = new TreeSet&lt;${ElementType}&gt;();@MemberOrder(sequence="1")
-
-public SortedSet&lt;${ElementType}&gt; get${CollectionName}() {
-	return ${collectionName};
-}
-public void set${CollectionName}(final SortedSet&lt;${ElementType}&gt; ${collectionName}) {
-	this.${collectionName} = ${collectionName};
-}
-// }}</template><template autoinsert="true" context="java-members" deleted="false" description="JDO Property (simple - 1:1 unidir &amp; bidir - parent)" enabled="true" name="isjdp">// {{ ${PropertyName} (property)&#13;
-private ${PropertyType} ${propertyName};&#13;
-${:import(org.apache.isis.applib.annotation.MemberOrder,javax.jdo.annotations.Column)}@MemberOrder(sequence="1")&#13;
-@Column(allowsNull="${trueOrFalse}")&#13;
-public ${PropertyType} get${PropertyName}() {&#13;
-	return ${propertyName};&#13;
-}&#13;
-public void set${PropertyName}(final ${PropertyType} ${propertyName}) {&#13;
-	this.${propertyName} = ${propertyName};&#13;
-}&#13;
-// }}&#13;
-&#13;
-</template><template autoinsert="true" context="java-members" deleted="false" description="JDO Property (1:1 child)" enabled="true" name="isjdp-11c">// {{ ${PropertyName} (property)
-private ${PropertyType} ${propertyName};
-${:import(org.apache.isis.applib.annotation.MemberOrder,javax.jdo.annotations.Column,javax.jdo.annotations.Persistent)}@MemberOrder(sequence="1")
-@Column(allowsNull="${trueOrFalse}")
-@Persistent(mappedBy="${fieldOnChild}")
-public ${PropertyType} get${PropertyName}() {
-	return ${propertyName};
-}
-public void set${PropertyName}(final ${PropertyType} ${propertyName}) {
-	this.${propertyName} = ${propertyName};
-}
-// }}</template><template autoinsert="true" context="java-members" deleted="false" description="Lifecycle region" enabled="true" name="isl">// {{ Lifecycle methods&#13;
-${cursor}&#13;
-// }}&#13;
-&#13;
-</template><template autoinsert="true" context="java-members" deleted="false" description="Lifecycle - create" enabled="true" name="islc">public void created() {&#13;
-    ${cursor}// TODO: post-create&#13;
-}</template><template autoinsert="true" context="java-members" deleted="false" description="Lifecycle - load" enabled="true" name="isll">public void loading() {&#13;
-    ${cursor}// TODO: pre-load&#13;
-}&#13;
-public void loaded() {&#13;
-    // TODO: post-load&#13;
-}</template><template autoinsert="true" context="java-members" deleted="false" description="Lifecycle - persist" enabled="true" name="islp">public void persisting() {&#13;
-    ${cursor}// TODO: pre-persist&#13;
-}&#13;
-public void persisted() {&#13;
-    // TODO: post-persist&#13;
-}</template><template autoinsert="true" context="java-members" deleted="false" description="Lifecycle - remove" enabled="true" name="islr">public void removing() {&#13;
-    ${cursor}// TODO: pre-remove&#13;
-}&#13;
-public void removed() {&#13;
-    // TODO: post-remove&#13;
-}</template><template autoinsert="true" context="java-members" deleted="false" description="Lifecycle - update" enabled="true" name="islu">public void updating() {&#13;
-    ${cursor}// TODO: pre-update&#13;
-}&#13;
-public void updated() {&#13;
-    // TODO: post-update&#13;
-}</template><template autoinsert="true" context="java-members" deleted="false" description="Property" enabled="true" name="isp">// {{ ${PropertyName} (property)&#13;
-private ${PropertyType} ${propertyName};&#13;
-${:import(org.apache.isis.applib.annotation.MemberOrder)}@MemberOrder(sequence="1")&#13;
-public ${PropertyType} get${PropertyName}() {&#13;
-	return ${propertyName};&#13;
-}&#13;
-public void set${PropertyName}(final ${PropertyType} ${propertyName}) {&#13;
-	this.${propertyName} = ${propertyName};&#13;
-}&#13;
-// }}&#13;
-&#13;
-</template><template autoinsert="true" context="java-members" deleted="false" description="Property (1:1 bidir child)" enabled="true" name="isp-11c">public void modify${ParentPropertyName}(final ${ParentPropertyType} ${parentPropertyName}) {&#13;
-    ${ParentPropertyType} current${ParentPropertyName} = get${ParentPropertyName}();&#13;
-	// check for no-op&#13;
-	if (${parentPropertyName} == null || &#13;
-		${parentPropertyName}.equals(current${ParentPropertyName})) {&#13;
-		return;&#13;
-	}&#13;
-	// delegate to parent to associate&#13;
-	${parentPropertyName}.modify${ChildPropertyNameInParent}(this);&#13;
-	// additional business logic&#13;
-	onModify${ParentPropertyName}(current${ParentPropertyName}, ${parentPropertyName});&#13;
-}&#13;
-public void clear${PropertyName}() {&#13;
-    ${ParentPropertyType} current${ParentPropertyName} = get${ParentPropertyName}();&#13;
-	// check for no-op&#13;
-	if (current${ParentPropertyName} == null) {&#13;
-		return;&#13;
-	}&#13;
-	// delegate to parent to dissociate&#13;
-	current${ParentPropertyName}.clear${ChildPropertyNameInParent}();&#13;
-	// additional business logic&#13;
-	onClear${ParentPropertyName}(current${ParentPropertyName});&#13;
-}</template><template autoinsert="true" context="java-members" deleted="false" description="Property (1:1 bidir parent)" enabled="true" name="isp-11p">public void modify${ChildPropertyName}(final ${ChildPropertyType} ${childPropertyName}) {&#13;
-    ${ChildPropertyType} current${ChildPropertyName} = get${ChildPropertyName}();&#13;
-	// check for no-op&#13;
-	if (${childPropertyName} == null || &#13;
-		${childPropertyName}.equals(current${ChildPropertyName})) {&#13;
-		return;&#13;
-	}&#13;
-	// dissociate existing&#13;
-	clear${ChildPropertyName}();&#13;
-	// associate new&#13;
-	${childPropertyName}.set${ParentPropertyNameInChild}(this);&#13;
-	set${ChildPropertyName}(${childPropertyName});&#13;
-	// additional business logic&#13;
-	onModify${ChildPropertyName}(current${ChildPropertyName}, ${childPropertyName});&#13;
-}&#13;
-public void clear${ChildPropertyName}() {&#13;
-    ${ChildPropertyType} current${ChildPropertyName} = get${ChildPropertyName}();&#13;
-	// check for no-op&#13;
-	if (current${ChildPropertyName} == null) {&#13;
-		return;&#13;
-	}&#13;
-	// dissociate existing&#13;
-	current${ChildPropertyName}.set${ParentPropertyNameInChild}(null);&#13;
-	set${ChildPropertyName}(null);&#13;
-	// additional business logic&#13;
-	onClear${ChildPropertyName}(current${ChildPropertyName});&#13;
-}</template><template autoinsert="true" context="java-members" deleted="false" description="Property (m:1 bidir child)" enabled="true" name="isp-m1">public void modify${ParentPropertyName}(final ${ParentPropertyType} ${parentPropertyName}) {&#13;
-    ${ParentPropertyType} current${ParentPropertyName} = get${ParentPropertyName}();&#13;
-	// check for no-op&#13;
-	if (${parentPropertyName} == null || &#13;
-		${parentPropertyName}.equals(current${ParentPropertyName})) {&#13;
-		return;&#13;
-	}&#13;
-	// delegate to parent to associate&#13;
-	${parentPropertyName}.addTo${ChildCollectionNameInParent}(this);&#13;
-	// additional business logic&#13;
-	onModify${ParentPropertyName}(current${ParentPropertyName}, ${parentPropertyName});&#13;
-}&#13;
-public void clear${ParentPropertyName}() {&#13;
-    ${ParentPropertyType} current${ParentPropertyName} = get${ParentPropertyName}();&#13;
-	// check for no-op&#13;
-	if (current${ParentPropertyName} == null) {&#13;
-		return;&#13;
-	}&#13;
-	// delegate to parent to dissociate&#13;
-	current${ParentPropertyName}.removeFrom${ChildCollectionNameInParent}(this);&#13;
-	// additional business logic&#13;
-	onClear${ParentPropertyName}(current${ParentPropertyName});&#13;
-}</template><template autoinsert="true" context="java-members" deleted="false" description="Property choices" enabled="true" name="ispcho">${:import(java.util.List)}public List&lt;${PropertyType}&gt; choices${PropertyName}() {&#13;
-	return ${cursor}null; // TODO: return list of choices for property&#13;
-}</template><template autoinsert="true" context="java-members" deleted="false" description="Property defaults" enabled="true" name="ispdef">public ${PropertyType} default${PropertyName}() {&#13;
-	return ${cursor}null; // TODO: return default for property when first created&#13;
-}</template><template autoinsert="true" context="java-members" deleted="false" description="Property disabling" enabled="true" name="ispdis">public String disable${PropertyName}() {&#13;
-	return ${cursor}null; // TODO: return reason why property is disabled, null if editable&#13;
-}</template><template autoinsert="true" context="java-members" deleted="false" description="Property hiding" enabled="true" name="isphid">public boolean hide${PropertyName}() {&#13;
-	return ${cursor}false; // TODO: return true if hidden, false if visible&#13;
-}</template><template autoinsert="true" context="java-members" deleted="false" description="Property modify" enabled="true" name="ispmod">public void modify${PropertyName}(final ${PropertyType} ${propertyName}) {&#13;
-    ${PropertyType} current${PropertyName} = get${PropertyName}();&#13;
-	// check for no-op&#13;
-	if (${propertyName} == null || &#13;
-		${propertyName}.equals(current${PropertyName})) {&#13;
-		return;&#13;
-	}&#13;
-	// associate new&#13;
-	set${PropertyName}(${propertyName});&#13;
-	// additional business logic&#13;
-	onModify${PropertyName}(current${PropertyName}, ${propertyName});&#13;
-}&#13;
-public void clear${PropertyName}() {&#13;
-    ${PropertyType} current${PropertyName} = get${PropertyName}();&#13;
-	// check for no-op&#13;
-	if (current${PropertyName} == null) {&#13;
-		return;&#13;
-	}&#13;
-	// dissociate existing&#13;
-	set${PropertyName}(null);&#13;
-	// additional business logic&#13;
-	onClear${PropertyName}(current${PropertyName});&#13;
-}&#13;
-protected void onModify${PropertyName}(final ${PropertyType} old${PropertyName}, final ${PropertyType} new${PropertyName}) {&#13;
-}&#13;
-protected void onClear${PropertyName}(final ${PropertyType} old${PropertyName}) {&#13;
-}</template><template autoinsert="true" context="java-members" deleted="false" description="Property validation" enabled="true" name="ispval">public String validate${PropertyName}(final ${PropertyType} ${propertyName}) {&#13;
-	if (${propertyName} == null) return null;&#13;
-	return ${cursor}null; // TODO: return reason why proposed value is invalid, null if valid&#13;
-}</template><template autoinsert="true" context="java-members" deleted="false" description="Isis Section" enabled="true" name="iss">// {{ ${SectionName}
-${cursor}
-// }}</template><template autoinsert="true" context="java-members" deleted="false" description="Search for all" enabled="true" name="issa">// {{ all ${TypePlural}&#13;
-${:import(org.apache.isis.applib.annotation.Exploration,java.util.List)}@Exploration&#13;
-public List&lt;${Type}&gt; all${TypePlural}() {&#13;
-	return allInstances(${Type}.class);&#13;
-}&#13;
-// }}&#13;
-&#13;
-&#13;
-</template><template autoinsert="true" context="java-members" deleted="false" description="Search for all matching" enabled="true" name="issafil">// {{ all ${TypePlural} that ${filterDescription}&#13;
-${:import(org.apache.isis.applib.annotation.Exploration,org.apache.isis.applib.Filter,java.util.List)}@Exploration&#13;
-public List&lt;${Type}&gt; all${TypePlural}Matching(final Filter&lt;${Type}&gt; filter) {&#13;
-	return allMatches(${Type}.class, filter);&#13;
-}&#13;
-// }}&#13;
-&#13;
-&#13;
-</template><template autoinsert="true" context="java-members" deleted="false" description="Search for first matching" enabled="true" name="issffil">// {{ first ${Type} that ${filterDescription}&#13;
-${:import(org.apache.isis.applib.annotation.Exploration,org.apache.isis.applib.Filter,java.util.List)}@Exploration&#13;
-public ${Type} first${Type}Matching(final Filter&lt;${Type}&gt; filter) {&#13;
-	return firstMatch(${Type}.class, filter);&#13;
-}&#13;
-// }}&#13;
-</template><template autoinsert="true" context="java-members" deleted="false" description="Search for unique matching" enabled="true" name="issufil">// {{ unique ${Type} that ${filterDescription}&#13;
-${:import(org.apache.isis.applib.annotation.Exploration,org.apache.isis.applib.Filter,java.util.List)}@Exploration&#13;
-public ${Type} unique${Type}Matching(final Filter&lt;${Type}&gt; filter) {&#13;
-	return uniqueMatch(${Type}.class, filter);&#13;
-}&#13;
-// }}&#13;
-</template><template autoinsert="true" context="java-members" deleted="false" description="Object-level validation" enabled="true" name="isval">public String validate() {&#13;
-    ${cursor}// TODO: return reason why object is in invalid state (and so cannot be saved/updated), or null if ok&#13;
-}</template></templates>
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/resources/appendices/dev-env/eclipse/jmock2-templates.xml
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/resources/appendices/dev-env/eclipse/jmock2-templates.xml b/adocs/documentation/src/main/asciidoc/guides/dg/resources/appendices/dev-env/eclipse/jmock2-templates.xml
deleted file mode 100644
index 9f0f4a5..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/dg/resources/appendices/dev-env/eclipse/jmock2-templates.xml
+++ /dev/null
@@ -1,9 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?><templates><template autoinsert="true" context="java" deleted="false" description="JMock2 AutoMock Definition" enabled="true" name="jmautomock">${:import(org.jmock.auto.Mock)}@Mock&#13;
-private ${MockClass} mock${MockClass};&#13;
-</template><template autoinsert="true" context="java" deleted="false" description="JMock2 Context field" enabled="true" name="jmcontext">${:import(org.jmock.Mockery,org.jmock.integration.junit4.JUnit4Mockery)}private Mockery context = new JUnit4Mockery();&#13;
-</template><template autoinsert="true" context="java" deleted="false" description="JMock2 Expectations" enabled="true" name="jmexpectations">${:import(org.jmock.Expectations)}context.checking(new Expectations() {{&#13;
-    ${cursor}&#13;
-}});</template><template autoinsert="true" context="java" deleted="false" description="JMock2 Mock Definition" enabled="true" name="jmmock">${MockClass} ${mockObject} = context.mock(${MockClass}.class);</template><template autoinsert="true" context="java" deleted="false" description="JMock2 Rule (Isis variant)" enabled="true" name="jmrule">${:import(org.junit.Rule,org.apache.isis.core.unittestsupport.jmocking.JUnitRuleMockery2,org.apache.isis.core.unittestsupport.jmocking.JUnitRuleMockery2.Mode)}@Rule&#13;
-public JUnitRuleMockery2 context = JUnitRuleMockery2.createFor(Mode.INTERFACES_AND_CLASSES${cursor});&#13;
-&#13;
-</template><template autoinsert="true" context="java" deleted="false" description="JMock2 RunWith" enabled="true" name="jmrunwith">${:import(org.junit.runner.RunWith,org.jmock.integration.junit4.JMock)}@RunWith(JMock.class)</template><template autoinsert="true" context="java" deleted="false" description="JMock2 Expectation Return Value" enabled="true" name="jmvalue">will(returnValue(${cursor}));</template></templates>
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/resources/appendices/dev-env/eclipse/junit4-templates.xml
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/resources/appendices/dev-env/eclipse/junit4-templates.xml b/adocs/documentation/src/main/asciidoc/guides/dg/resources/appendices/dev-env/eclipse/junit4-templates.xml
deleted file mode 100644
index 6af90cb..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/dg/resources/appendices/dev-env/eclipse/junit4-templates.xml
+++ /dev/null
@@ -1,13 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?><templates><template autoinsert="true" context="java" deleted="false" description="JUnit4 After Method" enabled="true" name="juafter">${:import(org.junit.After)}@After&#13;
-public void tearDown() throws Exception {&#13;
-	${cursor}&#13;
-}&#13;
-</template><template autoinsert="true" context="java" deleted="false" description="JUnit4 AssertThat" enabled="true" name="juassertThat">${:importStatic(org.junit.Assert.assertThat,'org.hamcrest.CoreMatchers.*')}assertThat(${object}, ${matcher});</template><template autoinsert="true" context="java" deleted="false" description="JUnit4 Before Method" enabled="true" name="jubefore">${:import(org.junit.Before)}@Before&#13;
-public void setUp() throws Exception {&#13;
-	${cursor}&#13;
-}&#13;
-</template><template autoinsert="true" context="java" deleted="false" description="JUnit4 Test Method" enabled="true" name="jutest">${:import(org.junit.Test)}@Test&#13;
-public void ${xxx}() throws Exception {&#13;
-	${cursor}&#13;
-}&#13;
-</template></templates>
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/resources/appendices/dev-env/intellij/.gitignore
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/resources/appendices/dev-env/intellij/.gitignore b/adocs/documentation/src/main/asciidoc/guides/dg/resources/appendices/dev-env/intellij/.gitignore
deleted file mode 100644
index 27620d5..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/dg/resources/appendices/dev-env/intellij/.gitignore
+++ /dev/null
@@ -1 +0,0 @@
-!*.jar

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/resources/appendices/dev-env/intellij/isis-settings-code-style.jar
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/resources/appendices/dev-env/intellij/isis-settings-code-style.jar b/adocs/documentation/src/main/asciidoc/guides/dg/resources/appendices/dev-env/intellij/isis-settings-code-style.jar
deleted file mode 100644
index b2ad298..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/resources/appendices/dev-env/intellij/isis-settings-code-style.jar and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/resources/appendices/dev-env/intellij/isis-settings-file-templates.jar
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/resources/appendices/dev-env/intellij/isis-settings-file-templates.jar b/adocs/documentation/src/main/asciidoc/guides/dg/resources/appendices/dev-env/intellij/isis-settings-file-templates.jar
deleted file mode 100644
index c64ef96..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/resources/appendices/dev-env/intellij/isis-settings-file-templates.jar and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/resources/appendices/dev-env/intellij/isis-settings-live-templates.jar
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/resources/appendices/dev-env/intellij/isis-settings-live-templates.jar b/adocs/documentation/src/main/asciidoc/guides/dg/resources/appendices/dev-env/intellij/isis-settings-live-templates.jar
deleted file mode 100644
index 69ff3e4..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/resources/appendices/dev-env/intellij/isis-settings-live-templates.jar and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/resources/appendices/dev-env/intellij/other/.gitignore
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/resources/appendices/dev-env/intellij/other/.gitignore b/adocs/documentation/src/main/asciidoc/guides/dg/resources/appendices/dev-env/intellij/other/.gitignore
deleted file mode 100644
index 27620d5..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/dg/resources/appendices/dev-env/intellij/other/.gitignore
+++ /dev/null
@@ -1 +0,0 @@
-!*.jar

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/resources/appendices/dev-env/intellij/other/dan-settings-keymaps.jar
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/resources/appendices/dev-env/intellij/other/dan-settings-keymaps.jar b/adocs/documentation/src/main/asciidoc/guides/dg/resources/appendices/dev-env/intellij/other/dan-settings-keymaps.jar
deleted file mode 100644
index 75d09be..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/resources/appendices/dev-env/intellij/other/dan-settings-keymaps.jar and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/resources/appendices/dev-env/intellij/other/dan-settings-uisettings.jar
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/resources/appendices/dev-env/intellij/other/dan-settings-uisettings.jar b/adocs/documentation/src/main/asciidoc/guides/dg/resources/appendices/dev-env/intellij/other/dan-settings-uisettings.jar
deleted file mode 100644
index 0787a69..0000000
Binary files a/adocs/documentation/src/main/asciidoc/guides/dg/resources/appendices/dev-env/intellij/other/dan-settings-uisettings.jar and /dev/null differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/resources/eclipse/isis-templates.xml
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/resources/eclipse/isis-templates.xml b/adocs/documentation/src/main/asciidoc/guides/dg/resources/eclipse/isis-templates.xml
new file mode 100644
index 0000000..f8ea500
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/resources/eclipse/isis-templates.xml
@@ -0,0 +1,465 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  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.
+-->
+<templates><template autoinsert="true" context="java-members" deleted="false" description="Action" enabled="true" name="isa">// {{ ${actionName} (action)&#13;
+${:import(org.apache.isis.applib.annotation.MemberOrder)}@MemberOrder(sequence="1")&#13;
+public ${ReturnType} ${actionName}(final ${ParameterType} ${parameterType}) {&#13;
+	return ${cursor}null; // TODO: business logic here&#13;
+}&#13;
+// }}&#13;
+&#13;
+</template><template autoinsert="true" context="java-members" deleted="false" description="Action argument N choices" enabled="true" name="isacho">${:import(java.util.Collections,java.util.List)}public List&lt;${ParameterType}&gt; choices${ParameterNumThenCapitalizedActionName}() {&#13;
+	return ${cursor}Collections.emptyList(); // TODO: return list of choices for argument N&#13;
+}</template><template autoinsert="true" context="java-members" deleted="false" description="Action argument defaults" enabled="true" name="isadef">public ${ParameterType} default${ParameterNumThenCapitalizedActionName}() {&#13;
+	return ${cursor}null; // TODO: return default for argument N&#13;
+}</template><template autoinsert="true" context="java-members" deleted="false" description="Action disabling" enabled="true" name="isadis">public String disable${ActionName}() {&#13;
+	return ${cursor}null; // TODO: return reason why action disabled, null if enabled&#13;
+}</template><template autoinsert="true" context="java-members" deleted="false" description="Action hiding" enabled="true" name="isahid">public boolean hide${ActionName}() {&#13;
+	return ${cursor}false; // TODO: return true if action is hidden, false if visible&#13;
+}</template><template autoinsert="true" context="java-members" deleted="false" description="Action validation" enabled="true" name="isaval">public String validate${ActionName}(final ${ParameterType} ${parameterType}) {&#13;
+	return ${cursor}null; // TODO: return reason why action arguments are invalid, null if ok&#13;
+}</template><template autoinsert="true" context="java-members" deleted="false" description="Collection (1:m bidir parent)" enabled="true" name="isc-1m">public void addTo${ChildCollectionName}(final ${ChildElementType} ${childElementName}) {&#13;
+	// check for no-op&#13;
+	if (${childElementName} == null || &#13;
+		get${ChildCollectionName}().contains(${childElementName})) {&#13;
+		return;&#13;
+	}&#13;
+	// dissociate arg from its current parent (if any).&#13;
+	${childElementName}.clear${ParentPropertyNameInChild}();&#13;
+	// associate arg&#13;
+	${childElementName}.set${ParentPropertyNameInChild}(this);&#13;
+	get${ChildCollectionName}().add(${childElementName});&#13;
+	// additional business logic&#13;
+	onAddTo${ChildCollectionName}(${childElementName});&#13;
+}&#13;
+public void removeFrom${ChildCollectionName}(final ${ChildElementType} ${childElementName}) {&#13;
+	// check for no-op&#13;
+	if (${childElementName} == null || &#13;
+		!get${ChildCollectionName}().contains(${childElementName})) {&#13;
+		return;&#13;
+	}&#13;
+	// dissociate arg&#13;
+	${childElementName}.set${ParentPropertyNameInChild}(null);&#13;
+	get${ChildCollectionName}().remove(${childElementName});&#13;
+	// additional business logic&#13;
+	onRemoveFrom${ChildCollectionName}(${childElementName});&#13;
+}</template><template autoinsert="true" context="java-members" deleted="false" description="Collection (m:m bidir child)" enabled="true" name="isc-mmc">public void addTo${ParentCollectionName}(final ${ParentElementType} ${parentElementName}) {&#13;
+	// check for no-op&#13;
+	if (${parentElementName} == null || &#13;
+		get${ParentCollectionName}().contains(${parentElementName})) {&#13;
+		return;&#13;
+	}&#13;
+	// delegate to parent to add&#13;
+	${parentElementName}.addTo${ChildCollectionNameInParent}(this);&#13;
+	// additional business logic&#13;
+	onAddTo${ParentCollectionName}(${parentElementName});&#13;
+}&#13;
+public void removeFrom${ParentCollectionName}(final ${ParentElementType} ${parentElementName}) {&#13;
+	// check for no-op&#13;
+	if (${parentElementName} == null || &#13;
+		!get${ParentCollectionName}().contains(${parentElementName})) {&#13;
+		return;&#13;
+	}&#13;
+	// delegate to parent to remove&#13;
+	${parentElementName}.removeFrom${ChildCollectionNameInParent}(this);&#13;
+	// additional business logic&#13;
+	onRemoveFrom${ParentCollectionName}(${parentElementName});&#13;
+}</template><template autoinsert="true" context="java-members" deleted="false" description="Collection (m:m bidir parent)" enabled="true" name="isc-mmp">public void addTo${ChildCollectionName}(final ${ChildElementType} ${childElementName}) {&#13;
+	// check for no-op&#13;
+	if (${childElementName} == null || &#13;
+		get${ChildCollectionName}().contains(${childElementName})) {&#13;
+		return;&#13;
+	}&#13;
+	// dissociate arg from its current parent (if any).&#13;
+	${childElementName}.removeFrom${ParentCollectionNameInChild}(this);&#13;
+	// associate arg&#13;
+	${childElementName}.get${ParentCollectionNameInChild}().add(this);&#13;
+	get${ChildCollectionName}().add(${childElementName});&#13;
+	// additional business logic&#13;
+	onAddTo${ChildCollectionName}(${childElementName});&#13;
+}&#13;
+public void removeFrom${ChildCollectionName}(final ${ChildElementType} ${childElementName}) {&#13;
+	// check for no-op&#13;
+	if (${childElementName} == null || &#13;
+		!get${ChildCollectionName}().contains(${childElementName})) {&#13;
+		return;&#13;
+	}&#13;
+	// dissociate arg&#13;
+	${childElementName}.get${ParentCollectionNameInChild}().remove(this);&#13;
+	get${ChildCollectionName}().remove(${childElementName});&#13;
+	// additional business logic&#13;
+	onRemoveFrom${ChildCollectionName}(${childElementName});&#13;
+}</template><template autoinsert="true" context="java-members" deleted="false" description="Collection disabling" enabled="true" name="iscdis">public String disable${CollectionName}() {&#13;
+	return ${cursor}null; // TODO: return reason why collection read-only, null if editable&#13;
+}</template><template autoinsert="true" context="java-members" deleted="false" description="Collection hiding" enabled="true" name="ischid">public boolean hide${CollectionName}() {&#13;
+	return ${cursor}false; // TODO: return true if hidden, false otherwise&#13;
+}</template><template autoinsert="true" context="java-members" deleted="false" description="Collection (list)" enabled="true" name="iscl">// {{ ${CollectionName} (Collection)&#13;
+${:import(java.util.List,java.util.ArrayList,org.apache.isis.applib.annotation.MemberOrder)}private List&lt;${ElementType}&gt; ${collectionName} = new ArrayList&lt;${ElementType}&gt;();&#13;
+@MemberOrder(sequence="1")&#13;
+public List&lt;${ElementType}&gt; get${CollectionName}() {&#13;
+	return ${collectionName};&#13;
+}&#13;
+public void set${CollectionName}(final List&lt;${ElementType}&gt; ${collectionName}) {&#13;
+	this.${collectionName} = ${collectionName};&#13;
+}&#13;
+// }}&#13;
+&#13;
+</template><template autoinsert="true" context="java-members" deleted="false" description="Collection modify" enabled="true" name="iscmod">public void addTo${CollectionName}(final ${ElementType} ${elementName}) {&#13;
+	// check for no-op&#13;
+	if (${elementName} == null || &#13;
+		get${CollectionName}().contains(${elementName})) {&#13;
+		return;&#13;
+	}&#13;
+	// associate new&#13;
+	get${CollectionName}().add(${elementName});&#13;
+    // additional business logic&#13;
+    onAddTo${CollectionName}(${elementName});&#13;
+}&#13;
+public void removeFrom${CollectionName}(final ${ElementType} ${elementName}) {&#13;
+	// check for no-op&#13;
+	if (${elementName} == null || &#13;
+		!get${CollectionName}().contains(${elementName})) {&#13;
+		return;&#13;
+	}&#13;
+	// dissociate existing&#13;
+	get${CollectionName}().remove(${elementName});&#13;
+    // additional business logic&#13;
+    onRemoveFrom${CollectionName}(${elementName});&#13;
+}&#13;
+protected void onAddTo${CollectionName}(final ${ElementType} ${elementName}) {&#13;
+}&#13;
+protected void onRemoveFrom${CollectionName}(final ${ElementType} ${elementName}) {&#13;
+}</template><template autoinsert="true" context="java-members" deleted="false" description="Collection (set)" enabled="true" name="iscs">// {{ ${CollectionName} (Collection)&#13;
+${:import(java.util.Set,java.util.LinkedHashSet,org.apache.isis.applib.annotation.MemberOrder)}private Set&lt;${ElementType}&gt; ${collectionName} = new LinkedHashSet&lt;${ElementType}&gt;();&#13;
+@MemberOrder(sequence="1")&#13;
+public Set&lt;${ElementType}&gt; get${CollectionName}() {&#13;
+	return ${collectionName};&#13;
+}&#13;
+public void set${CollectionName}(final Set&lt;${ElementType}&gt; ${collectionName}) {&#13;
+	this.${collectionName} = ${collectionName};&#13;
+}&#13;
+// }}&#13;
+&#13;
+</template><template autoinsert="true" context="java-members" deleted="false" description="Collection validation" enabled="true" name="iscval">public String validateAddTo${CollectionName}(final ${ElementType} ${elementName}) {&#13;
+	return ${cursor}null; // TODO: return reason why argument cannot be added, null if ok to add&#13;
+}&#13;
+public String validateRemoveFrom${CollectionName}(final ${ElementType} ${elementName}) {&#13;
+	return null; // TODO: return reason why argument cannot be removed, null if ok to remove&#13;
+}&#13;
+&#13;
+</template><template autoinsert="true" context="java-members" deleted="false" description="Dependencies region" enabled="true" name="isd">// {{ injected dependencies&#13;
+${cursor}&#13;
+// }}&#13;
+&#13;
+</template><template autoinsert="true" context="java-members" deleted="false" description="Dependencies - injected service" enabled="true" name="isds">// {{ injected: ${ServiceType}&#13;
+private ${ServiceType} ${serviceType};&#13;
+public void set${ServiceType}(final ${ServiceType} ${serviceType}) {&#13;
+	this.${serviceType} = ${serviceType};&#13;
+}&#13;
+// }}&#13;
+&#13;
+</template><template autoinsert="true" context="java-members" deleted="false" description="Factory - new instance (persistent)" enabled="true" name="isfp">// {{ Create new (already persisted) ${Type}&#13;
+public ${Type} new${Type}() {&#13;
+	${Type} ${type} = newTransientInstance(${Type}.class);&#13;
+	${cursor}// TODO: set up any properties&#13;
+&#13;
+	persist(${type});&#13;
+	return ${type};&#13;
+}&#13;
+// }}</template><template autoinsert="true" context="java-members" deleted="false" description="Factory - new instance (transient)" enabled="true" name="isft">// {{ Create new (still transient) ${Type}&#13;
+public ${Type} new${InstanceOfType}() {&#13;
+	${Type} ${type} = newTransientInstance(${Type}.class);&#13;
+	${cursor}// TODO: set up any properties&#13;
+&#13;
+	return ${type};&#13;
+}&#13;
+// }}</template><template autoinsert="true" context="java-members" deleted="false" description="Identification region" enabled="true" name="isid">// {{ Identification&#13;
+${cursor}&#13;
+// }}&#13;
+&#13;
+</template><template autoinsert="true" context="java-members" deleted="false" description="Identification - icon" enabled="true" name="isidicon">public String iconName() {&#13;
+	return ${cursor}null; // TODO: return name of image file (without suffix)&#13;
+}</template><template autoinsert="true" context="java-members" deleted="false" description="Identification - title" enabled="true" name="isidtitle">public String title() {&#13;
+    ${:import(org.apache.isis.applib.util.TitleBuffer)}final TitleBuffer buf = new TitleBuffer();&#13;
+    ${cursor}// TODO: append to TitleBuffer, typically value properties&#13;
+	return buf.toString();&#13;
+}</template><template autoinsert="true" context="java-members" deleted="false" description="JDO Collection (1:n bidir, foreign key)" enabled="true" name="isjdc-1n-b-fk">// {{ ${CollectionName} (Collection)
+${:import(java.util.SortedSet,java.util.TreeSet,org.apache.isis.applib.annotation.MemberOrder,javax.jdo.annotations.Persistent)}@Persistent(mappedBy="${elementNameInChild}", dependentElement="${trueOrFalse}")
+private SortedSet&lt;${ElementType}&gt; ${collectionName} = new TreeSet&lt;${ElementType}&gt;();
+@MemberOrder(sequence="1")
+public SortedSet&lt;${ElementType}&gt; get${CollectionName}() {
+return ${collectionName};
+}
+public void set${CollectionName}(final SortedSet&lt;${ElementType}&gt; ${collectionName}) {
+this.${collectionName} = ${collectionName};
+}
+// }}</template><template autoinsert="true" context="java-members" deleted="false" description="JDO Collection (1:n bidir, join table)" enabled="true" name="isjdc-1n-b-jt">// {{ ${CollectionName} (Collection)
+${:import(java.util.SortedSet,java.util.TreeSet,org.apache.isis.applib.annotation.MemberOrder,javax.jdo.annotations.Persitent,javax.jdo.annotations.Join)}@Persistent(mappedBy="${elementNameInChild}", dependentElement="${trueOrFalse}")
+@Join
+private SortedSet&lt;${ElementType}&gt; ${collectionName} = new TreeSet&lt;${ElementType}&gt;();
+@MemberOrder(sequence="1")
+public SortedSet&lt;${ElementType}&gt; get${CollectionName}() {
+return ${collectionName};
+}
+public void set${CollectionName}(final SortedSet&lt;${ElementType}&gt; ${collectionName}) {
+this.${collectionName} = ${collectionName};
+}
+// }}</template><template autoinsert="true" context="java-members" deleted="false" description="JDO Collection (1:n unidir, foreign key)" enabled="true" name="isjdc-1n-u-fk">// {{ ${CollectionName} (Collection)
+${:import(java.util.SortedSet,java.util.TreeSet,org.apache.isis.applib.annotation.MemberOrder,javax.jdo.annotations.Element)}
+@Element(column="${ColumnName}", dependent="${trueOrFalse}")
+private SortedSet&lt;${ElementType}&gt; ${collectionName} = new TreeSet&lt;${ElementType}&gt;();
+@MemberOrder(sequence="1")
+public SortedSet&lt;${ElementType}&gt; get${CollectionName}() {
+return ${collectionName};
+}
+public void set${CollectionName}(final SortedSet&lt;${ElementType}&gt; ${collectionName}) {
+this.${collectionName} = ${collectionName};
+}
+// }}</template><template autoinsert="true" context="java-members" deleted="false" description="JDO Collection (1:n unidir, join table)" enabled="true" name="isjdc-1n-u-jt">// {{ ${CollectionName} (Collection)
+${:import(java.util.SortedSet,java.util.TreeSet,org.apache.isis.applib.annotation.MemberOrder,javax.jdo.annotations.Join,javax.jdo.annotations.Element)}@Join
+@Element(dependent="${trueOrFalse}")
+private SortedSet&lt;${ElementType}&gt; ${collectionName} = new TreeSet&lt;${ElementType}&gt;();
+@MemberOrder(sequence="1")
+public SortedSet&lt;${ElementType}&gt; get${CollectionName}() {
+return ${collectionName};
+}
+public void set${CollectionName}(final SortedSet&lt;${ElementType}&gt; ${collectionName}) {
+this.${collectionName} = ${collectionName};
+}
+// }}</template><template autoinsert="true" context="java-members" deleted="false" description="JDO Collection (m:n bidir - child)" enabled="true" name="isjdc-mn-ub-c">// {{ ${CollectionName} (Collection)
+${:import(java.util.SortedSet,java.util.TreeSet,org.apache.isis.applib.annotation.MemberOrder,javax.jdo.annotations.Persistent)}@Persistent(mappedBy="${ChildCollectionNameInParent}")
+private SortedSet&lt;${ElementType}&gt; ${collectionName} = new TreeSet&lt;${ElementType}&gt;();
+public SortedSet&lt;${ElementType}&gt; get${CollectionName}() {
+return ${collectionName};
+}
+public void set${CollectionName}(final SortedSet&lt;${ElementType}&gt; ${collectionName}) {
+this.${collectionName} = ${collectionName};
+}
+// }}</template><template autoinsert="true" context="java-members" deleted="false" description="JDO Collection (m:n unidir &amp; bidir - parent)" enabled="true" name="isjdc-mn-ub-p">// {{ ${CollectionName} (Collection)
+${:import(java.util.SortedSet,java.util.TreeSet,org.apache.isis.applib.annotation.MemberOrder,javax.jdo.annotations.Persistent,javax.jdo.annotations.Join,javax.jdo.annotations.Element)}@Persistent(table="${TableName}")
+@Join(column="${ThisEntityFieldName}")
+@Element(column="${RelatedEntityFieldName}")
+private SortedSet&lt;${ElementType}&gt; ${collectionName} = new TreeSet&lt;${ElementType}&gt;();@MemberOrder(sequence="1")
+
+public SortedSet&lt;${ElementType}&gt; get${CollectionName}() {
+	return ${collectionName};
+}
+public void set${CollectionName}(final SortedSet&lt;${ElementType}&gt; ${collectionName}) {
+	this.${collectionName} = ${collectionName};
+}
+// }}</template><template autoinsert="true" context="java-members" deleted="false" description="JDO Property (simple - 1:1 unidir &amp; bidir - parent)" enabled="true" name="isjdp">// {{ ${PropertyName} (property)&#13;
+private ${PropertyType} ${propertyName};&#13;
+${:import(org.apache.isis.applib.annotation.MemberOrder,javax.jdo.annotations.Column)}@MemberOrder(sequence="1")&#13;
+@Column(allowsNull="${trueOrFalse}")&#13;
+public ${PropertyType} get${PropertyName}() {&#13;
+	return ${propertyName};&#13;
+}&#13;
+public void set${PropertyName}(final ${PropertyType} ${propertyName}) {&#13;
+	this.${propertyName} = ${propertyName};&#13;
+}&#13;
+// }}&#13;
+&#13;
+</template><template autoinsert="true" context="java-members" deleted="false" description="JDO Property (1:1 child)" enabled="true" name="isjdp-11c">// {{ ${PropertyName} (property)
+private ${PropertyType} ${propertyName};
+${:import(org.apache.isis.applib.annotation.MemberOrder,javax.jdo.annotations.Column,javax.jdo.annotations.Persistent)}@MemberOrder(sequence="1")
+@Column(allowsNull="${trueOrFalse}")
+@Persistent(mappedBy="${fieldOnChild}")
+public ${PropertyType} get${PropertyName}() {
+	return ${propertyName};
+}
+public void set${PropertyName}(final ${PropertyType} ${propertyName}) {
+	this.${propertyName} = ${propertyName};
+}
+// }}</template><template autoinsert="true" context="java-members" deleted="false" description="Lifecycle region" enabled="true" name="isl">// {{ Lifecycle methods&#13;
+${cursor}&#13;
+// }}&#13;
+&#13;
+</template><template autoinsert="true" context="java-members" deleted="false" description="Lifecycle - create" enabled="true" name="islc">public void created() {&#13;
+    ${cursor}// TODO: post-create&#13;
+}</template><template autoinsert="true" context="java-members" deleted="false" description="Lifecycle - load" enabled="true" name="isll">public void loading() {&#13;
+    ${cursor}// TODO: pre-load&#13;
+}&#13;
+public void loaded() {&#13;
+    // TODO: post-load&#13;
+}</template><template autoinsert="true" context="java-members" deleted="false" description="Lifecycle - persist" enabled="true" name="islp">public void persisting() {&#13;
+    ${cursor}// TODO: pre-persist&#13;
+}&#13;
+public void persisted() {&#13;
+    // TODO: post-persist&#13;
+}</template><template autoinsert="true" context="java-members" deleted="false" description="Lifecycle - remove" enabled="true" name="islr">public void removing() {&#13;
+    ${cursor}// TODO: pre-remove&#13;
+}&#13;
+public void removed() {&#13;
+    // TODO: post-remove&#13;
+}</template><template autoinsert="true" context="java-members" deleted="false" description="Lifecycle - update" enabled="true" name="islu">public void updating() {&#13;
+    ${cursor}// TODO: pre-update&#13;
+}&#13;
+public void updated() {&#13;
+    // TODO: post-update&#13;
+}</template><template autoinsert="true" context="java-members" deleted="false" description="Property" enabled="true" name="isp">// {{ ${PropertyName} (property)&#13;
+private ${PropertyType} ${propertyName};&#13;
+${:import(org.apache.isis.applib.annotation.MemberOrder)}@MemberOrder(sequence="1")&#13;
+public ${PropertyType} get${PropertyName}() {&#13;
+	return ${propertyName};&#13;
+}&#13;
+public void set${PropertyName}(final ${PropertyType} ${propertyName}) {&#13;
+	this.${propertyName} = ${propertyName};&#13;
+}&#13;
+// }}&#13;
+&#13;
+</template><template autoinsert="true" context="java-members" deleted="false" description="Property (1:1 bidir child)" enabled="true" name="isp-11c">public void modify${ParentPropertyName}(final ${ParentPropertyType} ${parentPropertyName}) {&#13;
+    ${ParentPropertyType} current${ParentPropertyName} = get${ParentPropertyName}();&#13;
+	// check for no-op&#13;
+	if (${parentPropertyName} == null || &#13;
+		${parentPropertyName}.equals(current${ParentPropertyName})) {&#13;
+		return;&#13;
+	}&#13;
+	// delegate to parent to associate&#13;
+	${parentPropertyName}.modify${ChildPropertyNameInParent}(this);&#13;
+	// additional business logic&#13;
+	onModify${ParentPropertyName}(current${ParentPropertyName}, ${parentPropertyName});&#13;
+}&#13;
+public void clear${PropertyName}() {&#13;
+    ${ParentPropertyType} current${ParentPropertyName} = get${ParentPropertyName}();&#13;
+	// check for no-op&#13;
+	if (current${ParentPropertyName} == null) {&#13;
+		return;&#13;
+	}&#13;
+	// delegate to parent to dissociate&#13;
+	current${ParentPropertyName}.clear${ChildPropertyNameInParent}();&#13;
+	// additional business logic&#13;
+	onClear${ParentPropertyName}(current${ParentPropertyName});&#13;
+}</template><template autoinsert="true" context="java-members" deleted="false" description="Property (1:1 bidir parent)" enabled="true" name="isp-11p">public void modify${ChildPropertyName}(final ${ChildPropertyType} ${childPropertyName}) {&#13;
+    ${ChildPropertyType} current${ChildPropertyName} = get${ChildPropertyName}();&#13;
+	// check for no-op&#13;
+	if (${childPropertyName} == null || &#13;
+		${childPropertyName}.equals(current${ChildPropertyName})) {&#13;
+		return;&#13;
+	}&#13;
+	// dissociate existing&#13;
+	clear${ChildPropertyName}();&#13;
+	// associate new&#13;
+	${childPropertyName}.set${ParentPropertyNameInChild}(this);&#13;
+	set${ChildPropertyName}(${childPropertyName});&#13;
+	// additional business logic&#13;
+	onModify${ChildPropertyName}(current${ChildPropertyName}, ${childPropertyName});&#13;
+}&#13;
+public void clear${ChildPropertyName}() {&#13;
+    ${ChildPropertyType} current${ChildPropertyName} = get${ChildPropertyName}();&#13;
+	// check for no-op&#13;
+	if (current${ChildPropertyName} == null) {&#13;
+		return;&#13;
+	}&#13;
+	// dissociate existing&#13;
+	current${ChildPropertyName}.set${ParentPropertyNameInChild}(null);&#13;
+	set${ChildPropertyName}(null);&#13;
+	// additional business logic&#13;
+	onClear${ChildPropertyName}(current${ChildPropertyName});&#13;
+}</template><template autoinsert="true" context="java-members" deleted="false" description="Property (m:1 bidir child)" enabled="true" name="isp-m1">public void modify${ParentPropertyName}(final ${ParentPropertyType} ${parentPropertyName}) {&#13;
+    ${ParentPropertyType} current${ParentPropertyName} = get${ParentPropertyName}();&#13;
+	// check for no-op&#13;
+	if (${parentPropertyName} == null || &#13;
+		${parentPropertyName}.equals(current${ParentPropertyName})) {&#13;
+		return;&#13;
+	}&#13;
+	// delegate to parent to associate&#13;
+	${parentPropertyName}.addTo${ChildCollectionNameInParent}(this);&#13;
+	// additional business logic&#13;
+	onModify${ParentPropertyName}(current${ParentPropertyName}, ${parentPropertyName});&#13;
+}&#13;
+public void clear${ParentPropertyName}() {&#13;
+    ${ParentPropertyType} current${ParentPropertyName} = get${ParentPropertyName}();&#13;
+	// check for no-op&#13;
+	if (current${ParentPropertyName} == null) {&#13;
+		return;&#13;
+	}&#13;
+	// delegate to parent to dissociate&#13;
+	current${ParentPropertyName}.removeFrom${ChildCollectionNameInParent}(this);&#13;
+	// additional business logic&#13;
+	onClear${ParentPropertyName}(current${ParentPropertyName});&#13;
+}</template><template autoinsert="true" context="java-members" deleted="false" description="Property choices" enabled="true" name="ispcho">${:import(java.util.List)}public List&lt;${PropertyType}&gt; choices${PropertyName}() {&#13;
+	return ${cursor}null; // TODO: return list of choices for property&#13;
+}</template><template autoinsert="true" context="java-members" deleted="false" description="Property defaults" enabled="true" name="ispdef">public ${PropertyType} default${PropertyName}() {&#13;
+	return ${cursor}null; // TODO: return default for property when first created&#13;
+}</template><template autoinsert="true" context="java-members" deleted="false" description="Property disabling" enabled="true" name="ispdis">public String disable${PropertyName}() {&#13;
+	return ${cursor}null; // TODO: return reason why property is disabled, null if editable&#13;
+}</template><template autoinsert="true" context="java-members" deleted="false" description="Property hiding" enabled="true" name="isphid">public boolean hide${PropertyName}() {&#13;
+	return ${cursor}false; // TODO: return true if hidden, false if visible&#13;
+}</template><template autoinsert="true" context="java-members" deleted="false" description="Property modify" enabled="true" name="ispmod">public void modify${PropertyName}(final ${PropertyType} ${propertyName}) {&#13;
+    ${PropertyType} current${PropertyName} = get${PropertyName}();&#13;
+	// check for no-op&#13;
+	if (${propertyName} == null || &#13;
+		${propertyName}.equals(current${PropertyName})) {&#13;
+		return;&#13;
+	}&#13;
+	// associate new&#13;
+	set${PropertyName}(${propertyName});&#13;
+	// additional business logic&#13;
+	onModify${PropertyName}(current${PropertyName}, ${propertyName});&#13;
+}&#13;
+public void clear${PropertyName}() {&#13;
+    ${PropertyType} current${PropertyName} = get${PropertyName}();&#13;
+	// check for no-op&#13;
+	if (current${PropertyName} == null) {&#13;
+		return;&#13;
+	}&#13;
+	// dissociate existing&#13;
+	set${PropertyName}(null);&#13;
+	// additional business logic&#13;
+	onClear${PropertyName}(current${PropertyName});&#13;
+}&#13;
+protected void onModify${PropertyName}(final ${PropertyType} old${PropertyName}, final ${PropertyType} new${PropertyName}) {&#13;
+}&#13;
+protected void onClear${PropertyName}(final ${PropertyType} old${PropertyName}) {&#13;
+}</template><template autoinsert="true" context="java-members" deleted="false" description="Property validation" enabled="true" name="ispval">public String validate${PropertyName}(final ${PropertyType} ${propertyName}) {&#13;
+	if (${propertyName} == null) return null;&#13;
+	return ${cursor}null; // TODO: return reason why proposed value is invalid, null if valid&#13;
+}</template><template autoinsert="true" context="java-members" deleted="false" description="Isis Section" enabled="true" name="iss">// {{ ${SectionName}
+${cursor}
+// }}</template><template autoinsert="true" context="java-members" deleted="false" description="Search for all" enabled="true" name="issa">// {{ all ${TypePlural}&#13;
+${:import(org.apache.isis.applib.annotation.Exploration,java.util.List)}@Exploration&#13;
+public List&lt;${Type}&gt; all${TypePlural}() {&#13;
+	return allInstances(${Type}.class);&#13;
+}&#13;
+// }}&#13;
+&#13;
+&#13;
+</template><template autoinsert="true" context="java-members" deleted="false" description="Search for all matching" enabled="true" name="issafil">// {{ all ${TypePlural} that ${filterDescription}&#13;
+${:import(org.apache.isis.applib.annotation.Exploration,org.apache.isis.applib.Filter,java.util.List)}@Exploration&#13;
+public List&lt;${Type}&gt; all${TypePlural}Matching(final Filter&lt;${Type}&gt; filter) {&#13;
+	return allMatches(${Type}.class, filter);&#13;
+}&#13;
+// }}&#13;
+&#13;
+&#13;
+</template><template autoinsert="true" context="java-members" deleted="false" description="Search for first matching" enabled="true" name="issffil">// {{ first ${Type} that ${filterDescription}&#13;
+${:import(org.apache.isis.applib.annotation.Exploration,org.apache.isis.applib.Filter,java.util.List)}@Exploration&#13;
+public ${Type} first${Type}Matching(final Filter&lt;${Type}&gt; filter) {&#13;
+	return firstMatch(${Type}.class, filter);&#13;
+}&#13;
+// }}&#13;
+</template><template autoinsert="true" context="java-members" deleted="false" description="Search for unique matching" enabled="true" name="issufil">// {{ unique ${Type} that ${filterDescription}&#13;
+${:import(org.apache.isis.applib.annotation.Exploration,org.apache.isis.applib.Filter,java.util.List)}@Exploration&#13;
+public ${Type} unique${Type}Matching(final Filter&lt;${Type}&gt; filter) {&#13;
+	return uniqueMatch(${Type}.class, filter);&#13;
+}&#13;
+// }}&#13;
+</template><template autoinsert="true" context="java-members" deleted="false" description="Object-level validation" enabled="true" name="isval">public String validate() {&#13;
+    ${cursor}// TODO: return reason why object is in invalid state (and so cannot be saved/updated), or null if ok&#13;
+}</template></templates>
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/resources/eclipse/jmock2-templates.xml
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/resources/eclipse/jmock2-templates.xml b/adocs/documentation/src/main/asciidoc/guides/dg/resources/eclipse/jmock2-templates.xml
new file mode 100644
index 0000000..9f0f4a5
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/resources/eclipse/jmock2-templates.xml
@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?><templates><template autoinsert="true" context="java" deleted="false" description="JMock2 AutoMock Definition" enabled="true" name="jmautomock">${:import(org.jmock.auto.Mock)}@Mock&#13;
+private ${MockClass} mock${MockClass};&#13;
+</template><template autoinsert="true" context="java" deleted="false" description="JMock2 Context field" enabled="true" name="jmcontext">${:import(org.jmock.Mockery,org.jmock.integration.junit4.JUnit4Mockery)}private Mockery context = new JUnit4Mockery();&#13;
+</template><template autoinsert="true" context="java" deleted="false" description="JMock2 Expectations" enabled="true" name="jmexpectations">${:import(org.jmock.Expectations)}context.checking(new Expectations() {{&#13;
+    ${cursor}&#13;
+}});</template><template autoinsert="true" context="java" deleted="false" description="JMock2 Mock Definition" enabled="true" name="jmmock">${MockClass} ${mockObject} = context.mock(${MockClass}.class);</template><template autoinsert="true" context="java" deleted="false" description="JMock2 Rule (Isis variant)" enabled="true" name="jmrule">${:import(org.junit.Rule,org.apache.isis.core.unittestsupport.jmocking.JUnitRuleMockery2,org.apache.isis.core.unittestsupport.jmocking.JUnitRuleMockery2.Mode)}@Rule&#13;
+public JUnitRuleMockery2 context = JUnitRuleMockery2.createFor(Mode.INTERFACES_AND_CLASSES${cursor});&#13;
+&#13;
+</template><template autoinsert="true" context="java" deleted="false" description="JMock2 RunWith" enabled="true" name="jmrunwith">${:import(org.junit.runner.RunWith,org.jmock.integration.junit4.JMock)}@RunWith(JMock.class)</template><template autoinsert="true" context="java" deleted="false" description="JMock2 Expectation Return Value" enabled="true" name="jmvalue">will(returnValue(${cursor}));</template></templates>
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/resources/eclipse/junit4-templates.xml
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/resources/eclipse/junit4-templates.xml b/adocs/documentation/src/main/asciidoc/guides/dg/resources/eclipse/junit4-templates.xml
new file mode 100644
index 0000000..6af90cb
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/resources/eclipse/junit4-templates.xml
@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?><templates><template autoinsert="true" context="java" deleted="false" description="JUnit4 After Method" enabled="true" name="juafter">${:import(org.junit.After)}@After&#13;
+public void tearDown() throws Exception {&#13;
+	${cursor}&#13;
+}&#13;
+</template><template autoinsert="true" context="java" deleted="false" description="JUnit4 AssertThat" enabled="true" name="juassertThat">${:importStatic(org.junit.Assert.assertThat,'org.hamcrest.CoreMatchers.*')}assertThat(${object}, ${matcher});</template><template autoinsert="true" context="java" deleted="false" description="JUnit4 Before Method" enabled="true" name="jubefore">${:import(org.junit.Before)}@Before&#13;
+public void setUp() throws Exception {&#13;
+	${cursor}&#13;
+}&#13;
+</template><template autoinsert="true" context="java" deleted="false" description="JUnit4 Test Method" enabled="true" name="jutest">${:import(org.junit.Test)}@Test&#13;
+public void ${xxx}() throws Exception {&#13;
+	${cursor}&#13;
+}&#13;
+</template></templates>
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/resources/intellij/.gitignore
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/resources/intellij/.gitignore b/adocs/documentation/src/main/asciidoc/guides/dg/resources/intellij/.gitignore
new file mode 100644
index 0000000..27620d5
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/resources/intellij/.gitignore
@@ -0,0 +1 @@
+!*.jar

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/resources/intellij/isis-settings-code-style.jar
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/resources/intellij/isis-settings-code-style.jar b/adocs/documentation/src/main/asciidoc/guides/dg/resources/intellij/isis-settings-code-style.jar
new file mode 100644
index 0000000..b2ad298
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/resources/intellij/isis-settings-code-style.jar differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/resources/intellij/isis-settings-file-templates.jar
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/resources/intellij/isis-settings-file-templates.jar b/adocs/documentation/src/main/asciidoc/guides/dg/resources/intellij/isis-settings-file-templates.jar
new file mode 100644
index 0000000..c64ef96
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/resources/intellij/isis-settings-file-templates.jar differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/resources/intellij/isis-settings-live-templates.jar
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/resources/intellij/isis-settings-live-templates.jar b/adocs/documentation/src/main/asciidoc/guides/dg/resources/intellij/isis-settings-live-templates.jar
new file mode 100644
index 0000000..69ff3e4
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/resources/intellij/isis-settings-live-templates.jar differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/resources/intellij/other/.gitignore
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/resources/intellij/other/.gitignore b/adocs/documentation/src/main/asciidoc/guides/dg/resources/intellij/other/.gitignore
new file mode 100644
index 0000000..27620d5
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/resources/intellij/other/.gitignore
@@ -0,0 +1 @@
+!*.jar

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/resources/intellij/other/dan-settings-keymaps.jar
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/resources/intellij/other/dan-settings-keymaps.jar b/adocs/documentation/src/main/asciidoc/guides/dg/resources/intellij/other/dan-settings-keymaps.jar
new file mode 100644
index 0000000..75d09be
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/resources/intellij/other/dan-settings-keymaps.jar differ

http://git-wip-us.apache.org/repos/asf/isis/blob/add8cef9/adocs/documentation/src/main/asciidoc/guides/dg/resources/intellij/other/dan-settings-uisettings.jar
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/resources/intellij/other/dan-settings-uisettings.jar b/adocs/documentation/src/main/asciidoc/guides/dg/resources/intellij/other/dan-settings-uisettings.jar
new file mode 100644
index 0000000..0787a69
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/resources/intellij/other/dan-settings-uisettings.jar differ

[14/58] [abbrv] isis git commit: ISIS-1521: fixes xref links between guides

[da...@apache.org]

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout.adoc
index e8ed93a..ef22d3c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout.adoc
@@ -18,28 +18,28 @@ The table below summarizes the annotation's attributes.
 | Description
 
 
-|xref:rgant.adoc#_rgant-ActionLayout_bookmarking[`bookmarking()`]
+|xref:../rgant/rgant.adoc#_rgant-ActionLayout_bookmarking[`bookmarking()`]
 |`AS_ROOT`, `NEVER` +
 (`NEVER`)
-|indicates if an action (with safe xref:rgant.adoc#_rgant-Action_semantics[action semantics]) is automatically bookmarked.
+|indicates if an action (with safe xref:../rgant/rgant.adoc#_rgant-Action_semantics[action semantics]) is automatically bookmarked.
 
 
-|xref:rgant.adoc#_rgant-ActionLayout_contributedAs[`contributedAs()`]
+|xref:../rgant/rgant.adoc#_rgant-ActionLayout_contributedAs[`contributedAs()`]
 |`AS_BOTH`, `AS_ACTION`, `AS_ASSOCIATION`, `AS_NEITHER` +
 (`AS_BOTH`)
 |for a domain service action that can be contributed, whether to contribute as an action or as an association (ie a property or collection). +
 
-For a domain service action to be contributed, the domain services must have a xref:rgant.adoc#_rgant-DomainService_nature[nature] nature of either `VIEW` or `VIEW_CONTRIBUTIONS_ONLY`, and the action must have xref:rgant.adoc#_rgant-Action_semantics[safe action semantics], and takes a single argument, namely the contributee domain object.
+For a domain service action to be contributed, the domain services must have a xref:../rgant/rgant.adoc#_rgant-DomainService_nature[nature] nature of either `VIEW` or `VIEW_CONTRIBUTIONS_ONLY`, and the action must have xref:../rgant/rgant.adoc#_rgant-Action_semantics[safe action semantics], and takes a single argument, namely the contributee domain object.
 
 
-|xref:rgant.adoc#_rgant-ActionLayout_cssClass[`cssClass()`]
+|xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClass[`cssClass()`]
 |Any string valid as a CSS class
-|an additional CSS class around the HTML that represents for the action, to allow targetted styling in xref:rgcfg.adoc#_rgcfg_application-specific_application-css[`application.css`]. +
+|an additional CSS class around the HTML that represents for the action, to allow targetted styling in xref:../rgcfg/rgcfg.adoc#_rgcfg_application-specific_application-css[`application.css`]. +
 
 Supported by the xref:ugvw.adoc#[Wicket viewer] but currently ignored by the xref:ugvro.adoc#[RestfulObjects viewer].
 
 
-|xref:rgant.adoc#_rgant-ActionLayout_cssClassFa[`cssClassFa()`]
+|xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClassFa[`cssClassFa()`]
 |Any valid link:http://fortawesome.github.io/Font-Awesome/[Font awesome] icon name
 |specify a font awesome icon for the action's menu link or icon. +
 
@@ -50,26 +50,26 @@ Supported by the xref:ugvw.adoc#[Wicket viewer] but currently ignored by the xre
 |Positioning of the icon on the button/menu item.
 
 
-|xref:rgant.adoc#_rgant-ActionLayout_describedAs[`describedAs()`]
+|xref:../rgant/rgant.adoc#_rgant-ActionLayout_describedAs[`describedAs()`]
 |String.
 |provides a short description of the action, eg for rendering as a 'tool tip'.
 
 
-|xref:rgant.adoc#_rgant-ActionLayout_hidden[`hidden()`]
+|xref:../rgant/rgant.adoc#_rgant-ActionLayout_hidden[`hidden()`]
 |`EVERYWHERE`, `NOWHERE` +
 (`NOWHERE`)
 |indicates where (in the UI) the action should be hidden from the user.
 
 
-|xref:rgant.adoc#_rgant-ActionLayout_named[`named()`]
+|xref:../rgant/rgant.adoc#_rgant-ActionLayout_named[`named()`]
 |String.
 |to override the name inferred from the action's name in code. +
 
 A typical use case is if the desired name is a reserved Java keyword, such as `default` or `package`.
 
-|xref:rgant.adoc#_rgant-ActionLayout_position[`position()`]
+|xref:../rgant/rgant.adoc#_rgant-ActionLayout_position[`position()`]
 |`BELOW`, `RIGHT`, `PANEL`, `PANEL_DROPDOWN` (`BELOW`)
-|for actions associated (using xref:rgant.adoc#_rgant-MemberOrder[`@MemberOrder#named()`]) with properties, the positioning of the action's button with respect to the property
+|for actions associated (using xref:../rgant/rgant.adoc#_rgant-MemberOrder[`@MemberOrder#named()`]) with properties, the positioning of the action's button with respect to the property
 
 
 |===

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_bookmarking.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_bookmarking.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_bookmarking.adoc
index aa1c159..643f24e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_bookmarking.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_bookmarking.adoc
@@ -6,7 +6,7 @@
 
 
 
-The `bookmarking()` attribute indicates if an action (with safe xref:rgant.adoc#_rgant-Action_semantics[action semantics]) is automatically bookmarked. This attribute is also supported for  xref:rgant.adoc#_rgant-DomainObjectLayout_bookmarking[domain objects].
+The `bookmarking()` attribute indicates if an action (with safe xref:../rgant/rgant.adoc#_rgant-Action_semantics[action semantics]) is automatically bookmarked. This attribute is also supported for  xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_bookmarking[domain objects].
 
 
 
@@ -45,7 +45,7 @@ indicates that the `notYetComplete()` action is bookmarkable.
 
 [NOTE]
 ====
-The enum value `AS_CHILD` has no meaning for actions; it relates only to bookmarked xref:rgant.adoc#_rgant-DomainObject_bookmarking[domain object]s.
+The enum value `AS_CHILD` has no meaning for actions; it relates only to bookmarked xref:../rgant/rgant.adoc#_rgant-DomainObject_bookmarking[domain object]s.
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_contributedAs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_contributedAs.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_contributedAs.adoc
index 0f4c22e..cd1f9dc 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_contributedAs.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_contributedAs.adoc
@@ -10,7 +10,7 @@ For a domain service action that _can_ be contributed, the `contributedAs()` att
 
 The distinction between property or collection is automatic: if the action returns a `java.util.Collection` (or subtype) then the action is contributed as a collection; otherwise it is contributed as a property.
 
-For a domain service action to be contributed, the domain services must have a xref:rgant.adoc#_rgant-DomainService_nature[nature] nature of either `VIEW` or `VIEW_CONTRIBUTIONS_ONLY`, and the action must have xref:rgant.adoc#_rgant-Action_semantics[safe action semantics], and takes a single argument, namely the contributee domain object.
+For a domain service action to be contributed, the domain services must have a xref:../rgant/rgant.adoc#_rgant-DomainService_nature[nature] nature of either `VIEW` or `VIEW_CONTRIBUTIONS_ONLY`, and the action must have xref:../rgant/rgant.adoc#_rgant-Action_semantics[safe action semantics], and takes a single argument, namely the contributee domain object.
 
 For example:
 
@@ -43,7 +43,7 @@ public class OrderContributions {
 }
 ----
 
-In such cases, though, it would probably make more sense to annotate the action as either xref:rgant.adoc#_rgant-Action_hidden[hidden] or indeed xref:rgant.adoc#_rgant-Programmatic[`@Programmatic`].
+In such cases, though, it would probably make more sense to annotate the action as either xref:../rgant/rgant.adoc#_rgant-Action_hidden[hidden] or indeed xref:../rgant/rgant.adoc#_rgant-Programmatic[`@Programmatic`].
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_cssClass.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_cssClass.adoc
index 9acba07..56b6d84 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_cssClass.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_cssClass.adoc
@@ -6,9 +6,9 @@
 
 
 
-The `cssClass()` attribute can be used to render additional CSS classes in the HTML (a wrapping `<div>`) that represents the action.   xref:rgcfg.adoc#_rgcfg_application-specific_application-css[Application-specific CSS] can then be used to target and adjust the UI representation of that particular element.
+The `cssClass()` attribute can be used to render additional CSS classes in the HTML (a wrapping `<div>`) that represents the action.   xref:../rgcfg/rgcfg.adoc#_rgcfg_application-specific_application-css[Application-specific CSS] can then be used to target and adjust the UI representation of that particular element.
 
-This attribute can also be applied to xref:rgant.adoc#_rgant-DomainObjectLayout_cssClass[domain objects], xref:rgant.adoc#_rgant-ViewModelLayout_cssClass[view models],  xref:rgant.adoc#_rgant-PropertyLayout_cssClass[properties],  xref:rgant.adoc#_rgant-CollectionLayout_cssClass[collections] and xref:rgant.adoc#_rgant-ParameterLayout_cssClass[parameters].
+This attribute can also be applied to xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_cssClass[domain objects], xref:../rgant/rgant.adoc#_rgant-ViewModelLayout_cssClass[view models],  xref:../rgant/rgant.adoc#_rgant-PropertyLayout_cssClass[properties],  xref:../rgant/rgant.adoc#_rgant-CollectionLayout_cssClass[collections] and xref:../rgant/rgant.adoc#_rgant-ParameterLayout_cssClass[parameters].
 
 
 For example:
@@ -24,7 +24,7 @@ public class ToDoItem {
 
 [NOTE]
 ====
-The similar xref:rgant.adoc#_rgant-ActionLayout_cssClassFa[`@ActionLayout#cssClassFa()`] annotation attribute is also used as a hint
+The similar xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClassFa[`@ActionLayout#cssClassFa()`] annotation attribute is also used as a hint
 to apply CSS, specifically to add http://fortawesome.github.io/Font-Awesome/icons/[Font Awesome icons] on action menu items or buttons.
 ====
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_cssClassFa.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_cssClassFa.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_cssClassFa.adoc
index 40a609c..2b642cd 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_cssClassFa.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_cssClassFa.adoc
@@ -7,7 +7,7 @@
 
 The `cssClassFa()` attribute is used to specify the name of a link:http://fortawesome.github.io/Font-Awesome/icons/[Font Awesome icon] name, to be rendered on the action's representation as a button or menu item.    The related `cssClassFaPosition()` attribute specifies the positioning of the icon, to the left or the right of the text.
 
-These attributes can also be applied to xref:rgant.adoc#_rgant-DomainObjectLayout_cssClassFa[domain objects] and to xref:rgant.adoc#_rgant-ViewModelLayout_cssClassFa[view models] to specify the object's icon.
+These attributes can also be applied to xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_cssClassFa[domain objects] and to xref:../rgant/rgant.adoc#_rgant-ViewModelLayout_cssClassFa[view models] to specify the object's icon.
 
 
 For example:
@@ -54,6 +54,6 @@ can be used instead, eg:
 
 [NOTE]
 ====
-The similar xref:rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout#cssClass()`] annotation attribute is also used as a hint to apply CSS, but for wrapping the representation of an object or object member so that it can be styled in an application-specific way.
+The similar xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout#cssClass()`] annotation attribute is also used as a hint to apply CSS, but for wrapping the representation of an object or object member so that it can be styled in an application-specific way.
 ====
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_describedAs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_describedAs.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_describedAs.adoc
index d1fa462..7818a0d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_describedAs.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_describedAs.adoc
@@ -8,7 +8,7 @@
 
 The `describedAs()` attribute is used to provide a short description of the action to the user.  In the xref:ugvw.adoc#[Wicket viewer] it is displayed as a 'tool tip'.
 
-This attribute can also be specified for xref:rgant.adoc#_rgant-CollectionLayout_describedAs[collections],  xref:rgant.adoc#_rgant-PropertyLayout_describedAs[properties], xref:rgant.adoc#_rgant-ParameterLayout_describedAs[parameters], xref:rgant.adoc#_rgant-DomainObjectLayout_describedAs[domain objects] and xref:rgant.adoc#_rgant-ViewModelLayout_describedAs[view models].
+This attribute can also be specified for xref:../rgant/rgant.adoc#_rgant-CollectionLayout_describedAs[collections],  xref:../rgant/rgant.adoc#_rgant-PropertyLayout_describedAs[properties], xref:../rgant/rgant.adoc#_rgant-ParameterLayout_describedAs[parameters], xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_describedAs[domain objects] and xref:../rgant/rgant.adoc#_rgant-ViewModelLayout_describedAs[view models].
 
 
 For example:

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_hidden.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_hidden.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_hidden.adoc
index d901a64..a1ad7d4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_hidden.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_hidden.adoc
@@ -5,11 +5,11 @@
 :_imagesdir: images/
 
 
-The `hidden()` attribute indicates where (in the UI) the action should be hidden from the user.  This attribute can also be applied to xref:rgant.adoc#_rgant-PropertyLayout_hidden[properties] and xref:rgant.adoc#_rgant-CollectionLayout_hidden[collections].
+The `hidden()` attribute indicates where (in the UI) the action should be hidden from the user.  This attribute can also be applied to xref:../rgant/rgant.adoc#_rgant-PropertyLayout_hidden[properties] and xref:../rgant/rgant.adoc#_rgant-CollectionLayout_hidden[collections].
 
 [TIP]
 ====
-It is also possible to use xref:rgant.adoc#_rgant-Action_hidden[`@Action#hidden()`] to hide an action at the domain layer.  Both options are provided with a view that in the future the view-layer semantics may be under the control of (expert) users, whereas domain-layer semantics should never be overridden or modified by the user.
+It is also possible to use xref:../rgant/rgant.adoc#_rgant-Action_hidden[`@Action#hidden()`] to hide an action at the domain layer.  Both options are provided with a view that in the future the view-layer semantics may be under the control of (expert) users, whereas domain-layer semantics should never be overridden or modified by the user.
 ====
 
 For example:
@@ -50,7 +50,7 @@ can be used instead, eg:
 
 [NOTE]
 ====
-For actions of domain services the visibility is dependent upon its xref:rgant.adoc#_rgant-DomainService_nature[`@DomainService#nature()`] and also on whether it is contributed (as per  xref:rgant.adoc#_rgant-ActionLayout_contributedAs[`@ActionLayout#contributedAs()`]).
+For actions of domain services the visibility is dependent upon its xref:../rgant/rgant.adoc#_rgant-DomainService_nature[`@DomainService#nature()`] and also on whether it is contributed (as per  xref:../rgant/rgant.adoc#_rgant-ActionLayout_contributedAs[`@ActionLayout#contributedAs()`]).
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_named.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_named.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_named.adoc
index c18ba6b..d50b1f8 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_named.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_named.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-The `named()` attribute explicitly specifies the action's name, overriding the name that would normally be inferred from the Java source code.  This attribute can also be specified for xref:rgant.adoc#_rgant-CollectionLayout_named[collections], xref:rgant.adoc#_rgant-PropertyLayout_named[properties], xref:rgant.adoc#_rgant-ParameterLayout_named[parameters], xref:rgant.adoc#_rgant-DomainObjectLayout_named[domain objects], xref:rgant.adoc#_rgant-ViewModelLayout_named[view models] and xref:rgant.adoc#_rgant-DomainServiceLayout_named[domain services].
+The `named()` attribute explicitly specifies the action's name, overriding the name that would normally be inferred from the Java source code.  This attribute can also be specified for xref:../rgant/rgant.adoc#_rgant-CollectionLayout_named[collections], xref:../rgant/rgant.adoc#_rgant-PropertyLayout_named[properties], xref:../rgant/rgant.adoc#_rgant-ParameterLayout_named[parameters], xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_named[domain objects], xref:../rgant/rgant.adoc#_rgant-ViewModelLayout_named[view models] and xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_named[domain services].
 
 [TIP]
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_position.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_position.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_position.adoc
index 27d3f68..89cba44 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_position.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_position.adoc
@@ -8,7 +8,7 @@
 
 
 
-The `position()` attribute pertains only to actions that have been associated with properties using xref:rgant.adoc#_rgant-MemberOrder[`@MemberOrder#named()`].  For these actions, it specifies the positioning of the action's button with respect to the field representing the object property.
+The `position()` attribute pertains only to actions that have been associated with properties using xref:../rgant/rgant.adoc#_rgant-MemberOrder[`@MemberOrder#named()`].  For these actions, it specifies the positioning of the action's button with respect to the field representing the object property.
 
 The attribute can take one of four values: `BELOW`, `RIGHT`, `PANEL` or `PANEL_DROPDOWN`.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_command.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_command.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_command.adoc
index 759d684..16ab6ce 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_command.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_command.adoc
@@ -9,13 +9,13 @@ The `@Action(command=...)` attribute (and the related `@Action(commandPersistenc
 
 The annotation works with (and is influenced by the behaviour of) a number of domain services:
 
-* xref:rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`]
-* xref:rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`]
-* xref:rgsvc.adoc#_rgsvc_spi_BackgroundService[`BackgroundService`] and
-* xref:rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[`BackgroundCommandService`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_BackgroundService[`BackgroundService`] and
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[`BackgroundCommandService`]
 
 
-Each action invocation is reified by the xref:rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`] service into a `Command` object, capturing details of the target object, the action, the parameter arguments, the user, a timestamp and so on.
+Each action invocation is reified by the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`] service into a `Command` object, capturing details of the target object, the action, the parameter arguments, the user, a timestamp and so on.
 
 If an appropriate `CommandService` is configured (for example using (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module), then the `Command` itself is persisted.
 
@@ -28,9 +28,9 @@ If background ``Command``s are used, then an external scheduler, using xref:ugbt
 
 
 
-The `command()` attribute determines whether the action invocation should be reified into a `Command` object (by the xref:rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`] service).
+The `command()` attribute determines whether the action invocation should be reified into a `Command` object (by the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`] service).
 
-The default is `AS_CONFIGURED`, meaning that the xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.services.command.actions` is used to determine the whether the action is reified:
+The default is `AS_CONFIGURED`, meaning that the xref:../rgcfg/rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.services.command.actions` is used to determine the whether the action is reified:
 
 * `all` +
 +
@@ -48,7 +48,7 @@ If there is no configuration property in `isis.properties` then all actions are
 
 [NOTE]
 ====
-Note: `Command` reification does not necessarily imply that `Command` objects will be persisted; that depends on whether there is a xref:rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] configured that will persist said ``Command``s.
+Note: `Command` reification does not necessarily imply that `Command` objects will be persisted; that depends on whether there is a xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] configured that will persist said ``Command``s.
 ====
 
 This default can be overridden on an action-by-action basis; if `command()` is set to `ENABLED` then the action is reified irrespective of the configured value; if set to `DISABLED` then the action is NOT reified irrespective of the configured value.
@@ -86,7 +86,7 @@ public class Order {
 }
 ----
 
-will suppress the persistence of the `Command` object _unless_ a child background `Command` has been created in the body of the action by way of the xref:rgsvc.adoc#_rgsvc_api_BackgroundService[`BackgroundService`].
+will suppress the persistence of the `Command` object _unless_ a child background `Command` has been created in the body of the action by way of the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BackgroundService[`BackgroundService`].
 
 On the other hand:
 
@@ -112,7 +112,7 @@ will prevent the parent `Command` object from being persisted, _even if_ a child
 
 For persisted commands, the `commandExecuteIn()` attribute determines whether the `Command` should be executed in the foreground (the default) or executed in the background.
 
-Background execution means that the command is not executed immediately, but is available for a configured xref:rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[`BackgroundCommandService`] to execute, eg by way of an in-memory scheduler such as Quartz.  See xref:ugbtb.adoc#_ugbtb_headless-access_BackgroundCommandExecution[here] for further information on this topic.
+Background execution means that the command is not executed immediately, but is available for a configured xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[`BackgroundCommandService`] to execute, eg by way of an in-memory scheduler such as Quartz.  See xref:ugbtb.adoc#_ugbtb_headless-access_BackgroundCommandExecution[here] for further information on this topic.
 
 For example:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_domainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_domainEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_domainEvent.adoc
index b5bef05..af488f5 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_domainEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_domainEvent.adoc
@@ -13,7 +13,7 @@ Whenever a domain object (or list of domain objects) is to be rendered, the fram
 * pre-execute phase: before the invocation of the action
 * post-execute: after the invocation of the action
 
-Subscribers subscribe through the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] using either link:https://github.com/google/guava[Guava] or link:http://www.axonframework.org/[Axon Framework] annotations and can influence each of these phases.
+Subscribers subscribe through the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] using either link:https://github.com/google/guava[Guava] or link:http://www.axonframework.org/[Axon Framework] annotations and can influence each of these phases.
 
 By default the event raised is `ActionDomainEvent.Default`. For example:
 
@@ -29,8 +29,8 @@ public class ToDoItem {
 
 The `domainEvent()` attribute allows a custom subclass to be emitted allowing more precise subscriptions (to those
 subclasses) to be defined instead.  This attribute is also supported for
-xref:rgant.adoc#_rgant-Collection_domainEvent[collections] and
-xref:rgant.adoc#_rgant-Property_domainEvent[properties].
+xref:../rgant/rgant.adoc#_rgant-Collection_domainEvent[collections] and
+xref:../rgant/rgant.adoc#_rgant-Property_domainEvent[properties].
 
 For example:
 
@@ -60,7 +60,7 @@ rather than through the constructor.  This substantially reduces the boilerplate
 
 == Subscribers
 
-Subscribers (which must be domain services) subscribe using either the link:https://github.com/google/guava[Guava] API or (if the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] has been appropriately configured) using the link:http://www.axonframework.org/[Axon Framework] API.  The examples below use the Guava API.
+Subscribers (which must be domain services) subscribe using either the link:https://github.com/google/guava[Guava] API or (if the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] has been appropriately configured) using the link:http://www.axonframework.org/[Axon Framework] API.  The examples below use the Guava API.
 
 Subscribers can be either coarse-grained (if they subscribe to the top-level event type):
 
@@ -155,8 +155,8 @@ then no event will be posted.
 
 == Raising events programmatically
 
-Normally events are only raised for interactions through the UI. However, events can be raised programmatically either by calling the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] API directly, or by emulating the UI by
-wrapping the target object using the xref:rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`] domain service.
+Normally events are only raised for interactions through the UI. However, events can be raised programmatically either by calling the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] API directly, or by emulating the UI by
+wrapping the target object using the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`] domain service.
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_hidden.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_hidden.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_hidden.adoc
index 84c53df..1646495 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_hidden.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_hidden.adoc
@@ -7,11 +7,11 @@
 
 
 
-Actions can be hidden at the domain-level, indicating that they are not visible to the end-user.  This attribute can also be applied to xref:rgant.adoc#_rgant-Property_hidden[properties] and xref:rgant.adoc#_rgant-Collection_hidden[collections].
+Actions can be hidden at the domain-level, indicating that they are not visible to the end-user.  This attribute can also be applied to xref:../rgant/rgant.adoc#_rgant-Property_hidden[properties] and xref:../rgant/rgant.adoc#_rgant-Collection_hidden[collections].
 
 [TIP]
 ====
-It is also possible to use xref:rgant.adoc#_rgant-ActionLayout_hidden[`@ActionLayout#hidden()`] or xref:ugvw.adoc#_ugvw_layout_file-based[file-based layouts] such that the action can be hidden at the view layer.
+It is also possible to use xref:../rgant/rgant.adoc#_rgant-ActionLayout_hidden[`@ActionLayout#hidden()`] or xref:../ugvw/ugvw.adoc#_ugvw_layout_file-based[file-based layouts] such that the action can be hidden at the view layer.
 Both options are provided with a view that in the future the view-layer semantics may be under the control of (expert) users, whereas domain-layer semantics should never be overridden or modified by the user.
 ====
 
@@ -43,7 +43,7 @@ The other values of the `Where` enum have no meaning for a collection.
 
 [NOTE]
 ====
-For actions of domain services the visibility is dependent upon its xref:rgant.adoc#_rgant-DomainService_nature[`@DomainService#nature()`] and also on whether it is contributed (as per  xref:rgant.adoc#_rgant-ActionLayout_contributedAs[`@ActionLayout#contributedAs()`]).
+For actions of domain services the visibility is dependent upon its xref:../rgant/rgant.adoc#_rgant-DomainService_nature[`@DomainService#nature()`] and also on whether it is contributed (as per  xref:../rgant/rgant.adoc#_rgant-ActionLayout_contributedAs[`@ActionLayout#contributedAs()`]).
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_publishing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_publishing.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_publishing.adoc
index d5abc01..3c10f3c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_publishing.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_publishing.adoc
@@ -8,15 +8,15 @@
 
 
 The `publishing()` attribute determines whether and how an action invocation is published via the registered
-implementation of a xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`]) or
-xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`].  This attribute is also
-supported for xref:rgant.adoc#_rgant-DomainObject_publishing[domain objects], where it controls whether changed objects
-are published as events, and for xref:rgant.adoc#_rgant_Property_publishing[`@Property#publishing()`], where it controls
+implementation of a xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`]) or
+xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`].  This attribute is also
+supported for xref:../rgant/rgant.adoc#_rgant-DomainObject_publishing[domain objects], where it controls whether changed objects
+are published as events, and for xref:../rgant/rgant.adoc#_rgant_Property_publishing[`@Property#publishing()`], where it controls
 whether property edits are published as events.
 
 A common use case is to notify external "downstream" systems of changes in the state of the Isis application.
 The default value for the attribute is `AS_CONFIGURED`, meaning that the
-xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.services.publish.actions` is used to determine
+xref:../rgcfg/rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.services.publish.actions` is used to determine
 the whether the action is published:
 
 * `all` +
@@ -62,8 +62,8 @@ this should avoid the necessity to query back for additional information.
 
 [WARNING]
 ====
-Be aware that this attribute is only honoured by the (deprecated) xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`], so should itself be considered as deprecated.  It
-is ignored by the replacement xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`],
+Be aware that this attribute is only honoured by the (deprecated) xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`], so should itself be considered as deprecated.  It
+is ignored by the replacement xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`],
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_restrictTo.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_restrictTo.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_restrictTo.adoc
index f07ca6f..6b3728f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_restrictTo.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_restrictTo.adoc
@@ -7,7 +7,7 @@
 
 
 
-By default actions are available irrespective of the xref:rgcfg.adoc#_rgcfg_deployment-types[deployment mode].  The `restrictTo()` attribute specifies whether the action should instead be restricted to only available in prototyping mode.
+By default actions are available irrespective of the xref:../rgcfg/rgcfg.adoc#_rgcfg_deployment-types[deployment mode].  The `restrictTo()` attribute specifies whether the action should instead be restricted to only available in prototyping mode.
 
 For example:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_semantics.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_semantics.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_semantics.adoc
index 78e8ecf..e3f3a13 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_semantics.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_semantics.adoc
@@ -66,7 +66,7 @@ public class Customer {
 }
 ----
 
-Actions that are safe and request-cacheable automatically use the xref:rgsvc.adoc#_rgsvc_api_QueryResultsCache[`QueryResultsCache`] service to cache the result of the method.  Note though that the results of this caching will only be apparent if the action is invoked from another method using the xref:rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`] service.
+Actions that are safe and request-cacheable automatically use the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_QueryResultsCache[`QueryResultsCache`] service to cache the result of the method.  Note though that the results of this caching will only be apparent if the action is invoked from another method using the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`] service.
 
 Continuing the example above, imagine code that loops over a set of ``Order``s where each `Order` has an associated `Customer`.  We want to check the credit rating of each `Customer` (a potentially expensive operation) but we don't want to do it more than once per `Customer`.  Invoking through the `WrapperFactory` will allow us to accomplish this by exploiting the semantics of `checkCredit()` action:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_typeOf.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_typeOf.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_typeOf.adoc
index 22b6e58..ddc093d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_typeOf.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_typeOf.adoc
@@ -6,7 +6,7 @@
 
 
 
-The `typeOf()` attribute specifies the expected type of an element returned by the action (returning a collection), when for whatever reason the type cannot be inferred from the generic type, or to provide a hint about the actual run-time (as opposed to compile-time) type.  This attribute can also be specified for xref:rgant.adoc#_rgant-Collection_typeOf[collections].
+The `typeOf()` attribute specifies the expected type of an element returned by the action (returning a collection), when for whatever reason the type cannot be inferred from the generic type, or to provide a hint about the actual run-time (as opposed to compile-time) type.  This attribute can also be specified for xref:../rgant/rgant.adoc#_rgant-Collection_typeOf[collections].
 
 
 For example:

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection.adoc
index 569928b..6b508ce 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection.adoc
@@ -18,13 +18,13 @@ The table below summarizes the annotation's attributes.
 | Description
 
 
-|xref:rgant.adoc#_rgant-Collection_domainEvent[`domainEvent()`]
+|xref:../rgant/rgant.adoc#_rgant-Collection_domainEvent[`domainEvent()`]
 |subtype of `CollectionDomainEvent` +
 (`CollectionDomainEvent.Default`)
-|the event type to be posted to the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] to broadcast the collection's business rule checking (hide, disable, validate) and its modification (before and after).
+|the event type to be posted to the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] to broadcast the collection's business rule checking (hide, disable, validate) and its modification (before and after).
 
 
-|xref:rgant.adoc#_rgant-Collection_editing[`editing()`]
+|xref:../rgant/rgant.adoc#_rgant-Collection_editing[`editing()`]
 |`ENABLED`, `DISABLED`, `AS_CONFIGURED` +
 (`AS_CONFIGURED`)
 |whether a collection can be added to or removed from within the UI
@@ -35,13 +35,13 @@ The table below summarizes the annotation's attributes.
 |if `editing()` is `DISABLED`, provides a reason as to why.
 
 
-|xref:rgant.adoc#_rgant-Collection_hidden[`hidden()`]
+|xref:../rgant/rgant.adoc#_rgant-Collection_hidden[`hidden()`]
 |`EVERYWHERE`, `OBJECT_FORMS`, `NOWHERE` +
 (`NOWHERE`)
 |indicates where (in the UI) the collection should be hidden from the user.
 
 
-|xref:rgant.adoc#_rgant-Collection_notPersisted[`notPersisted()`]
+|xref:../rgant/rgant.adoc#_rgant-Collection_notPersisted[`notPersisted()`]
 |`true`, `false` +
 (`false`)
 |whether to exclude from snapshots. +
@@ -53,7 +53,7 @@ Collection must also be annotated with `@javax.jdo.annotations.NotPersistent` in
 
 
 
-|xref:rgant.adoc#_rgant-Collection_typeOf[`typeOf()`]
+|xref:../rgant/rgant.adoc#_rgant-Collection_typeOf[`typeOf()`]
 |
 |hints as to the run-time type of the objects within that collection (as a fallback)
 
@@ -88,7 +88,7 @@ public class ToDoItem {
 
 [TIP]
 ====
-The annotation is one of a handful (others including xref:rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`], xref:rgant.adoc#_rgant-Property[`@Property`] and xref:rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`]) that can also be applied to the field, rather than the getter method.  This is specifically
+The annotation is one of a handful (others including xref:../rgant/rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`], xref:../rgant/rgant.adoc#_rgant-Property[`@Property`] and xref:../rgant/rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`]) that can also be applied to the field, rather than the getter method.  This is specifically
 so that boilerplate-busting tools such as link:https://projectlombok.org/[Project Lombok] can be used.
 ====
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout.adoc
index 071ed02..88a0f52 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout.adoc
@@ -19,12 +19,12 @@ The table below summarizes the annotation's attributes.
 | Description
 
 
-|xref:rgant.adoc#_rgant-CollectionLayout_cssClass[`cssClass()`]
+|xref:../rgant/rgant.adoc#_rgant-CollectionLayout_cssClass[`cssClass()`]
 |Any string valid as a CSS class
-|the css class that a collection should have, to allow more targetted styling in xref:rgcfg.adoc#_rgcfg_application-specific_application-css[`application.css`]
+|the css class that a collection should have, to allow more targetted styling in xref:../rgcfg/rgcfg.adoc#_rgcfg_application-specific_application-css[`application.css`]
 
 
-|xref:rgant.adoc#_rgant-CollectionLayout_defaultView[`defaultView()`]
+|xref:../rgant/rgant.adoc#_rgant-CollectionLayout_defaultView[`defaultView()`]
 |`table`, `excel`, `calendar`, `map`, ...
 |Which view is selected by default, if multiple views are available.
 
@@ -32,18 +32,18 @@ See (non-ASF) link:http://isisaddons.org[Isis Addons] for further views.
 
 
 
-|xref:rgant.adoc#_rgant-CollectionLayout_describedAs[`describedAs()`]
+|xref:../rgant/rgant.adoc#_rgant-CollectionLayout_describedAs[`describedAs()`]
 |String.
 |description of this collection, eg to be rendered in a tooltip.
 
 
-|xref:rgant.adoc#_rgant-CollectionLayout_hidden[`hidden()`]
+|xref:../rgant/rgant.adoc#_rgant-CollectionLayout_hidden[`hidden()`]
 |`EVERYWHERE`, `OBJECT_FORMS`, `NOWHERE` +
 (`NOWHERE`)
 |indicates where (in the UI) the collection should be hidden from the user.
 
 
-|xref:rgant.adoc#_rgant-CollectionLayout_named[named()]
+|xref:../rgant/rgant.adoc#_rgant-CollectionLayout_named[named()]
 |String.
 |to override the name inferred from the collection's name in code. +
 
@@ -55,18 +55,18 @@ A typical use case is if the desired name is a reserved Java keyword, such as `d
 |whether to HTML escape the name of this property.
 
 
-|xref:rgant.adoc#_rgant-CollectionLayout_paged[`paged()`]
+|xref:../rgant/rgant.adoc#_rgant-CollectionLayout_paged[`paged()`]
 |Positive integer
 |the page size for instances of this class when rendered within a table.
 
 
-|xref:rgant.adoc#_rgant-CollectionLayout_render[`render()`]
+|xref:../rgant/rgant.adoc#_rgant-CollectionLayout_render[`render()`]
 |`EAGERLY`, `LAZILY` +
 (`LAZILY`)
 |whether the collection should be (eagerly) rendered open or (lazily) rendered closed
 
 
-|xref:rgant.adoc#_rgant-CollectionLayout_sortedBy[`sortedBy()`]
+|xref:../rgant/rgant.adoc#_rgant-CollectionLayout_sortedBy[`sortedBy()`]
 |Subclass of `java.util.Comparator` for element type
 |indicates that the elements in the `java.util.SortedSet` collection should be sorted according to a specified `Comparator` rather than their natural sort order.
 
@@ -105,7 +105,7 @@ As an alternative to using the `@CollectionLayout` annotation, a xref:ugvw.adoc#
 
 [TIP]
 ====
-The annotation is one of a handful (others including xref:rgant.adoc#_rgant-Collection[`@Collection`], xref:rgant.adoc#_rgant-Property[`@Property`] and xref:rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`]) that can also be applied to the field, rather than the getter method.  This is specifically
+The annotation is one of a handful (others including xref:../rgant/rgant.adoc#_rgant-Collection[`@Collection`], xref:../rgant/rgant.adoc#_rgant-Property[`@Property`] and xref:../rgant/rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`]) that can also be applied to the field, rather than the getter method.  This is specifically
 so that boilerplate-busting tools such as link:https://projectlombok.org/[Project Lombok] can be used.
 ====
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_cssClass.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_cssClass.adoc
index 479aea4..d5834c4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_cssClass.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_cssClass.adoc
@@ -5,9 +5,9 @@
 :_imagesdir: images/
 
 
-The `cssClass()` attribute can be used to render additional CSS classes in the HTML (a wrapping `<div>`) that represents the collection.   xref:rgcfg.adoc#_rgcfg_application-specific_application-css[Application-specific CSS] can then be used to target and adjust the UI representation of that particular element.
+The `cssClass()` attribute can be used to render additional CSS classes in the HTML (a wrapping `<div>`) that represents the collection.   xref:../rgcfg/rgcfg.adoc#_rgcfg_application-specific_application-css[Application-specific CSS] can then be used to target and adjust the UI representation of that particular element.
 
-This attribute can also be applied to xref:rgant.adoc#_rgant-DomainObjectLayout_cssClass[domain objects], xref:rgant.adoc#_rgant-ViewModelLayout_cssClass[view models], xref:rgant.adoc#_rgant-ActionLayout_cssClass[actions], xref:rgant.adoc#_rgant-PropertyLayout_cssClass[properties] and xref:rgant.adoc#_rgant-ParameterLayout_cssClass[parameters].
+This attribute can also be applied to xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_cssClass[domain objects], xref:../rgant/rgant.adoc#_rgant-ViewModelLayout_cssClass[view models], xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClass[actions], xref:../rgant/rgant.adoc#_rgant-PropertyLayout_cssClass[properties] and xref:../rgant/rgant.adoc#_rgant-ParameterLayout_cssClass[parameters].
 
 
 For example:

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_defaultView.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_defaultView.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_defaultView.adoc
index 65ff625..9955a3b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_defaultView.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_defaultView.adoc
@@ -38,6 +38,6 @@ can be used instead, eg:
 
 [NOTE]
 ====
-This attribute takes precedence over any value for the xref:rgant.adoc#_rgant-CollectionLayout_render[`@CollectionLayout#render()`] attribute.  For example, if the
+This attribute takes precedence over any value for the xref:../rgant/rgant.adoc#_rgant-CollectionLayout_render[`@CollectionLayout#render()`] attribute.  For example, if the
 `defaultView` attribute is defined to "table", then the table will be show even if `render` is set to `LAZILY`.
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_describedAs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_describedAs.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_describedAs.adoc
index 0b20afa..7695b9b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_describedAs.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_describedAs.adoc
@@ -7,7 +7,7 @@
 
 The `describedAs()` attribute is used to provide a short description of the collection to the user.  In the xref:ugvw.adoc#[Wicket viewer] it is displayed as a 'tool tip'.
 
-The `describedAs()` attribute can also be specified for xref:rgant.adoc#_rgant-PropertyLayout_describedAs[properties], xref:rgant.adoc#_rgant-ActionLayout_describedAs[actions], xref:rgant.adoc#_rgant-ParameterLayout_describedAs[parameters], xref:rgant.adoc#_rgant-DomainObjectLayout_describedAs[domain objects] and xref:rgant.adoc#_rgant-ViewModelLayout_describedAs[view models].
+The `describedAs()` attribute can also be specified for xref:../rgant/rgant.adoc#_rgant-PropertyLayout_describedAs[properties], xref:../rgant/rgant.adoc#_rgant-ActionLayout_describedAs[actions], xref:../rgant/rgant.adoc#_rgant-ParameterLayout_describedAs[parameters], xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_describedAs[domain objects] and xref:../rgant/rgant.adoc#_rgant-ViewModelLayout_describedAs[view models].
 
 
 For example:

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_hidden.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_hidden.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_hidden.adoc
index 4973e8a..5156638 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_hidden.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_hidden.adoc
@@ -5,12 +5,12 @@
 :_imagesdir: images/
 
 
-The `hidden()` attribute indicates where (in the UI) the collection should be hidden from the user.  This attribute can also be applied to xref:rgant.adoc#_rgant-ActionLayout_hidden[actions] and xref:rgant.adoc#_rgant-PropertyLayout_hidden[properties].
+The `hidden()` attribute indicates where (in the UI) the collection should be hidden from the user.  This attribute can also be applied to xref:../rgant/rgant.adoc#_rgant-ActionLayout_hidden[actions] and xref:../rgant/rgant.adoc#_rgant-PropertyLayout_hidden[properties].
 
 
 [TIP]
 ====
-It is also possible to use xref:rgant.adoc#_rgant-Collection_hidden[`@Collection#hidden()`] to hide an action at the domain layer.  Both options are provided with a view that in the future the view-layer semantics may be under the control of (expert) users, whereas domain-layer semantics should never be overridden or modified by the user.
+It is also possible to use xref:../rgant/rgant.adoc#_rgant-Collection_hidden[`@Collection#hidden()`] to hide an action at the domain layer.  Both options are provided with a view that in the future the view-layer semantics may be under the control of (expert) users, whereas domain-layer semantics should never be overridden or modified by the user.
 ====
 
 For example:

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_named.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_named.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_named.adoc
index a75e210..d58a60c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_named.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_named.adoc
@@ -6,7 +6,7 @@
 
 
 
-The `named()` attribute explicitly specifies the collection's name, overriding the name that would normally be inferred from the Java source code.  This attribute can also be specified for xref:rgant.adoc#_rgant-ActionLayout_named[actions], xref:rgant.adoc#_rgant-PropertyLayout_named[properties], xref:rgant.adoc#_rgant-ParameterLayout_named[parameters], xref:rgant.adoc#_rgant-DomainObjectLayout_named[domain objects], xref:rgant.adoc#_rgant-ViewModelLayout_named[view models] and xref:rgant.adoc#_rgant-DomainServiceLayout_named[domain services].
+The `named()` attribute explicitly specifies the collection's name, overriding the name that would normally be inferred from the Java source code.  This attribute can also be specified for xref:../rgant/rgant.adoc#_rgant-ActionLayout_named[actions], xref:../rgant/rgant.adoc#_rgant-PropertyLayout_named[properties], xref:../rgant/rgant.adoc#_rgant-ParameterLayout_named[parameters], xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_named[domain objects], xref:../rgant/rgant.adoc#_rgant-ViewModelLayout_named[view models] and xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_named[domain services].
 
 [TIP]
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_paged.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_paged.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_paged.adoc
index 4b0abed..f3d7569 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_paged.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_paged.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-The `paged()` attribute specifies the number of rows to display in a (parented) collection. This attribute can also be applied to xref:rgant.adoc#_rgant-DomainObjectLayout_paged[domain objects] and xref:rgant.adoc#_rgant-ViewModelLayout_paged[view models].
+The `paged()` attribute specifies the number of rows to display in a (parented) collection. This attribute can also be applied to xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_paged[domain objects] and xref:../rgant/rgant.adoc#_rgant-ViewModelLayout_paged[view models].
 
 
 [WARNING]
@@ -27,7 +27,7 @@ public class Order {
 ----
 
 
-It is also possible to specify a global default for the page size of standalone collections, using the xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.viewer.paged.parented`.
+It is also possible to specify a global default for the page size of standalone collections, using the xref:../rgcfg/rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.viewer.paged.parented`.
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_render.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_render.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_render.adoc
index 7462a18..eaeeda2 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_render.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_render.adoc
@@ -35,8 +35,8 @@ can be used instead, eg:
 
 [NOTE]
 ====
-Note that xref:ugfun.adoc#_ugfun_how-tos_contributed-members[contributed collections] (which, under the covers are just action invocations against a domain service) are always rendered eagerly.
+Note that xref:../ugfun/ugfun.adoc#_ugfun_how-tos_contributed-members[contributed collections] (which, under the covers are just action invocations against a domain service) are always rendered eagerly.
 
-Also, if a xref:rgant.adoc#_rgant-CollectionLayout_defaultView[`@CollectionLayout#defaultView()`] attribute has been specified then that will take precedence over the value of the `render()` attribute.
+Also, if a xref:../rgant/rgant.adoc#_rgant-CollectionLayout_defaultView[`@CollectionLayout#defaultView()`] attribute has been specified then that will take precedence over the value of the `render()` attribute.
 ====
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection_domainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection_domainEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection_domainEvent.adoc
index 51b2aee..254fa62 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection_domainEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection_domainEvent.adoc
@@ -13,14 +13,14 @@ Whenever a domain object (or list of domain objects) is to be rendered, the fram
 * pre-execute phase: before the modification of the collection
 * post-execute: after the modification of the collection
 
-Subscribers subscribe through the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] using either link:https://github.com/google/guava[Guava] or link:http://www.axonframework.org/[Axon Framework] annotations and can influence each of these phases.
+Subscribers subscribe through the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] using either link:https://github.com/google/guava[Guava] or link:http://www.axonframework.org/[Axon Framework] annotations and can influence each of these phases.
 
 
 [WARNING]
 ====
 The xref:ugvw.adoc#[Wicket viewer] does _not_ currently support the modification of collections; they are rendered read-only.  However, domain events are still relevant to determine if such collections should be hidden.
 
-The workaround is to create add/remove actions and use xref:rgant.adoc#_rgant-MemberOrder[UI hints] to render them close to the collection.
+The workaround is to create add/remove actions and use xref:../rgant/rgant.adoc#_rgant-MemberOrder[UI hints] to render them close to the collection.
 ====
 
 By default the event raised is `CollectionDomainEvent.Default`. For example:
@@ -36,8 +36,8 @@ public class ToDoItem {
 
 The `domainEvent()` attribute allows a custom subclass to be emitted allowing more precise subscriptions (to those
 subclasses) to be defined instead.  This attribute is also supported for
-xref:rgant.adoc#_rgant-Action_domainEvent[actions] and
-xref:rgant.adoc#_rgant-Property_domainEvent[properties].
+xref:../rgant/rgant.adoc#_rgant-Action_domainEvent[actions] and
+xref:../rgant/rgant.adoc#_rgant-Property_domainEvent[properties].
 
 
 For example:
@@ -73,7 +73,7 @@ rather than through the constructor.  This substantially reduces the boilerplate
 
 == Subscribers
 
-Subscribers (which must be domain services) subscribe using either the link:https://github.com/google/guava[Guava] API or (if the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] has been appropriately configured) using the link:http://www.axonframework.org/[Axon Framework] API.  The examples below use the Guava API.
+Subscribers (which must be domain services) subscribe using either the link:https://github.com/google/guava[Guava] API or (if the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] has been appropriately configured) using the link:http://www.axonframework.org/[Axon Framework] API.  The examples below use the Guava API.
 
 Subscribers can be either coarse-grained (if they subscribe to the top-level event type):
 
@@ -166,8 +166,8 @@ then no event will be posted.
 
 == Raising events programmatically
 
-Normally events are only raised for interactions through the UI. However, events can be raised programmatically either by calling the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] API directly, or by emulating the UI by
-wrapping the target object using the xref:rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`] domain service.
+Normally events are only raised for interactions through the UI. However, events can be raised programmatically either by calling the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] API directly, or by emulating the UI by
+wrapping the target object using the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`] domain service.
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection_editing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection_editing.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection_editing.adoc
index ed63939..3310952 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection_editing.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection_editing.adoc
@@ -6,7 +6,7 @@
 
 
 
-The `editing()` annotation indicates whether a collection can be added to or removed from within the UI.  This attribute can also be specified for xref:rgant.adoc#_rgant-Property_editing[properties], and can also be specified for the xref:rgant.adoc#_rgant-DomainObject_editing[domain object]
+The `editing()` annotation indicates whether a collection can be added to or removed from within the UI.  This attribute can also be specified for xref:../rgant/rgant.adoc#_rgant-Property_editing[properties], and can also be specified for the xref:../rgant/rgant.adoc#_rgant-DomainObject_editing[domain object]
 
 The related `editingDisabledReason()` attribute specifies the a hard-coded reason why the collection cannot be modified directly.
 
@@ -14,18 +14,18 @@ The related `editingDisabledReason()` attribute specifies the a hard-coded reaso
 ====
 The xref:ugvw.adoc#[Wicket viewer] does *not* currently support the modification of collections; they are rendered read-only.
 
-The workaround is to create add/remove actions and use xref:rgant.adoc#_rgant-MemberOrder[UI hints] to render them close to the collection.
+The workaround is to create add/remove actions and use xref:../rgant/rgant.adoc#_rgant-MemberOrder[UI hints] to render them close to the collection.
 ====
 
 Whether a collection is enabled or disabled depends upon these factors:
 
-* whether the domain object has been configured as immutable through the xref:rgant.adoc#_rgant-DomainObject_editing[`@DomainObject#editing()`] attribute
+* whether the domain object has been configured as immutable through the xref:../rgant/rgant.adoc#_rgant-DomainObject_editing[`@DomainObject#editing()`] attribute
 
-* else (that is, if the domain object's editability is specified as being `AS_CONFIGURED`), then the value of the xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.objects.editing`.  If set to `false`, then the object's collections (and properties) are *not* editable
+* else (that is, if the domain object's editability is specified as being `AS_CONFIGURED`), then the value of the xref:../rgcfg/rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.objects.editing`.  If set to `false`, then the object's collections (and properties) are *not* editable
 
 * else, then the value of the `@Collection(editing=...)` attribute itself.
 
-* else, the result of invoking any supporting xref:rgcms.adoc#_rgcms_methods_prefixes_disable[`disable...()`] supporting methods
+* else, the result of invoking any supporting xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_disable[`disable...()`] supporting methods
 
 
 Thus, to make a collection read-only even if the object would otherwise be editable, use:

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection_hidden.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection_hidden.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection_hidden.adoc
index e2feb1a..63da074 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection_hidden.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection_hidden.adoc
@@ -5,11 +5,11 @@
 :_imagesdir: images/
 
 
-Collections can be hidden at the domain-level, indicating that they are not visible to the end-user.  This attribute can also be applied to xref:rgant.adoc#_rgant-Action_hidden[actions] and xref:rgant.adoc#_rgant-Property_hidden[properties].
+Collections can be hidden at the domain-level, indicating that they are not visible to the end-user.  This attribute can also be applied to xref:../rgant/rgant.adoc#_rgant-Action_hidden[actions] and xref:../rgant/rgant.adoc#_rgant-Property_hidden[properties].
 
 [TIP]
 ====
-It is also possible to use xref:rgant.adoc#_rgant-CollectionLayout_hidden[`@CollectionLayout#hidden()`] or using xref:ugvw.adoc#_ugvw_layout_file-based[file-based layout] such that the collection can be hidden at the view layer.
+It is also possible to use xref:../rgant/rgant.adoc#_rgant-CollectionLayout_hidden[`@CollectionLayout#hidden()`] or using xref:ugvw.adoc#_ugvw_layout_file-based[file-based layout] such that the collection can be hidden at the view layer.
 Both options are provided with a view that in the future the view-layer semantics may be under the control of (expert) users, whereas domain-layer semantics should never be overridden or modified by the user.
 ====
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection_notPersisted.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection_notPersisted.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection_notPersisted.adoc
index cd33b91..0f6c19c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection_notPersisted.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection_notPersisted.adoc
@@ -6,7 +6,7 @@
 
 
 
-The (somewhat misnamed) `notPersisted()` attribute indicates that the collection should be excluded from any snapshots generated by the xref:rgsvc.adoc#_rgsvc_api_XmlSnapshotService[`XmlSnapshotService`].  This attribute is also supported for xref:rgant.adoc#_rgant-Property_notPersisted[properties].
+The (somewhat misnamed) `notPersisted()` attribute indicates that the collection should be excluded from any snapshots generated by the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_XmlSnapshotService[`XmlSnapshotService`].  This attribute is also supported for xref:../rgant/rgant.adoc#_rgant-Property_notPersisted[properties].
 
 
 [WARNING]

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection_typeOf.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection_typeOf.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection_typeOf.adoc
index cea1e14..00efb05 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection_typeOf.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection_typeOf.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-The `typeOf()` attribute specifies the expected type of an element contained within a collection when for whatever reason the type cannot be inferred from the generic type, or to provide a hint about the actual run-time (as opposed to compile-time) type.  This attribute can also be specified for xref:rgant.adoc#_rgant-Action_typeOf[actions].
+The `typeOf()` attribute specifies the expected type of an element contained within a collection when for whatever reason the type cannot be inferred from the generic type, or to provide a hint about the actual run-time (as opposed to compile-time) type.  This attribute can also be specified for xref:../rgant/rgant.adoc#_rgant-Action_typeOf[actions].
 
 For example:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Column.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Column.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Column.adoc
index a4a2f33..08451f0 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Column.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Column.adoc
@@ -34,11 +34,11 @@ public class Customer {
     public void setMiddleInitial(String middleInitial) { ... }
 ----
 
-Isis also provides xref:rgant.adoc#_rgant-Property_optionality[`@Property#optionality()`] attribute.  If both are specified, Apache Isis will check when it initializes for any contradictions, and will fail-fast with an appropriate error message in the log if there are.
+Isis also provides xref:../rgant/rgant.adoc#_rgant-Property_optionality[`@Property#optionality()`] attribute.  If both are specified, Apache Isis will check when it initializes for any contradictions, and will fail-fast with an appropriate error message in the log if there are.
 
 You should also be aware that in the lack of either the `@Column#allowsNull()` or the `@Property#optionality()` attributes, that the JDO and Apache Isis defaults differ.  Apache Isis rule is straight-forward: properties are assumed to be required.  JDO on the other hand specifies that only primitive types are mandatory; everything else is assumed to be optional.  Therefore a lack of either annotation can also trigger the fail-fast validation check.
 
-In the vast majority of cases you should be fine just to add the `@Column#allowsNull()` attribute to the getter.  But see the documentation for xref:rgant.adoc#_rgant-Property_optionality[`@Property#optionality()`] attribute for discussion on one or two minor edge cases.
+In the vast majority of cases you should be fine just to add the `@Column#allowsNull()` attribute to the getter.  But see the documentation for xref:../rgant/rgant.adoc#_rgant-Property_optionality[`@Property#optionality()`] attribute for discussion on one or two minor edge cases.
 
 
 
@@ -62,7 +62,7 @@ public class Customer {
     public void setLastName(String lastName) { ... }
 ----
 
-Isis also provides xref:rgant.adoc#_rgant-Property_maxLength[`@Property#maxLength()`] attribute.  If both are specified, Apache Isis will check when it initializes for any contradictions, and will fail-fast with an appropriate error message in the log if there are.
+Isis also provides xref:../rgant/rgant.adoc#_rgant-Property_maxLength[`@Property#maxLength()`] attribute.  If both are specified, Apache Isis will check when it initializes for any contradictions, and will fail-fast with an appropriate error message in the log if there are.
 
 
 
@@ -81,7 +81,7 @@ public class Customer {
     public void setTotalOrdersToDate(BigDecimal totalOrdersToDate) { ... }
 ----
 
-For ``BigDecimal``s it is also possible to specify the xref:rgant.adoc#_rgant-Digits[`@Digits`] annotation, whose form is `@Digits(integer, fraction)`.  There is a subtle difference here: while `@Column#scale()` corresponds to `@Digits#fraction()`, the value of `@Column#length()` (ie the precision) is actually the _sum_ of the `@Digits`' `integer()` and `fraction()` parts.
+For ``BigDecimal``s it is also possible to specify the xref:../rgant/rgant.adoc#_rgant-Digits[`@Digits`] annotation, whose form is `@Digits(integer, fraction)`.  There is a subtle difference here: while `@Column#scale()` corresponds to `@Digits#fraction()`, the value of `@Column#length()` (ie the precision) is actually the _sum_ of the `@Digits`' `integer()` and `fraction()` parts.
 
 If both are specified, Apache Isis will check when it initializes for any contradictions, and will fail-fast with an appropriate error message in the log if there are.
 
@@ -116,7 +116,7 @@ public class PartyRelationship {
 
 == Mapping ``Blob``s and ``Clob``s
 
-Isis provides custom value types for xref:rgcms.adoc#_rgcms_classes_value-types_Blob[`Blob`]s and xref:rgcms.adoc#_rgcms_classes_value-types_Clob[`Clob`]s.  These value types have multiple internal fields, meaning that they corresponding to multiple columns in the database.  Mapping this correctly requires using  `@Column` within JDO's `@Persistent` annotation.
+Isis provides custom value types for xref:../rgcms/rgcms.adoc#_rgcms_classes_value-types_Blob[`Blob`]s and xref:../rgcms/rgcms.adoc#_rgcms_classes_value-types_Clob[`Clob`]s.  These value types have multiple internal fields, meaning that they corresponding to multiple columns in the database.  Mapping this correctly requires using  `@Column` within JDO's `@Persistent` annotation.
 
 For example, here's how to map a `Blob` (taken from (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp]):
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Digits.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Digits.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Digits.adoc
index af51285..16a8a42 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Digits.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Digits.adoc
@@ -28,7 +28,7 @@ public void setCost(final BigDecimal cost) {
         :null;
 }
 ----
-<1> the xref:rgant.adoc#_rgant-Column[`@Column#scale()`] attribute must be ...
+<1> the xref:../rgant/rgant.adoc#_rgant-Column[`@Column#scale()`] attribute must be ...
 <2> ... consistent with `@Digits#fraction()`
 <3> the correct idiom when setting a new value is to normalized to the correct scale
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Discriminator.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Discriminator.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Discriminator.adoc
index efa54a3..6f7716d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Discriminator.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Discriminator.adoc
@@ -21,12 +21,12 @@ This value is used internally to generate a string representation of an objects
 This can appear in several contexts, including:
 
 * as the value of `Bookmark#getObjectType()` and in the `toString()` value of `Bookmark`
- (see xref:rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`])
+ (see xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`])
  ** and thus in the "table-of-two-halves" pattern, as per (non-ASF) http://github.com/isisaddons/isis-module-poly[Isis addons' poly] module
-* in the serialization of `OidDto` in the xref:rgcms.adoc#_rgcms_schema-cmd[command] and xref:rgcms.adoc#_rgcms_schema-ixn[interaction] schemas
+* in the serialization of `OidDto` in the xref:../rgcms/rgcms.adoc#_rgcms_schema-cmd[command] and xref:../rgcms/rgcms.adoc#_rgcms_schema-ixn[interaction] schemas
 * in the URLs of the xref:ugvro.adoc#[RestfulObjects viewer]
 * in the URLs of the xref:ugvw.adoc#[Wicket viewer] (in general and in particular if xref:ugvw.adoc#_ugvw_features_hints-and-copy-url[copying URLs])
-* in XML snapshots generated by the xref:rgsvc.adoc#_rgsvc_api_XmlSnapshotService[`XmlSnapshotService`]
+* in XML snapshots generated by the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_XmlSnapshotService[`XmlSnapshotService`]
 
 
 
@@ -49,9 +49,9 @@ has an object type of `custmgmt.Customer`.
 
 The rules of precedence for determining a domain object's object type are:
 
-1. xref:rgant.adoc#_rgant_Discriminator[`@Discriminator`]
+1. xref:../rgant/rgant.adoc#_rgant_Discriminator[`@Discriminator`]
 2. `@DomainObject#objectType`
-3. xref:rgant.adoc#_rgant_PersistenceCapable[`@PersistenceCapable`], if at least the `schema` attribute is defined.  +
+3. xref:../rgant/rgant.adoc#_rgant_PersistenceCapable[`@PersistenceCapable`], if at least the `schema` attribute is defined.  +
 +
 If both `schema` and `table` are defined, then the value is "`schema.table`".
 If only `schema` is defined, then the value is "`schema.className`".

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject.adoc
index 584471f..acd363ac 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject.adoc
@@ -19,15 +19,15 @@ The table below summarizes the annotation's attributes.
 | Description
 
 
-|xref:rgant.adoc#_rgant-DomainObject_auditing[`auditing()`]
+|xref:../rgant/rgant.adoc#_rgant-DomainObject_auditing[`auditing()`]
 |`AS_CONFIGURED`, `ENABLED`, `DISABLED` +
 (`AS_CONFIGURED`)
 |indicates whether each of the changed properties of an object should be submitted to the registered
-xref:rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`] (deprecated) or (its replacement)
-xref:rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditerService`]
+xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`] (deprecated) or (its replacement)
+xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditerService`]
 
 
-|xref:rgant.adoc#_rgant-DomainObject_autoCompleteRepository[`autoCompleteRepository()`]
+|xref:../rgant/rgant.adoc#_rgant-DomainObject_autoCompleteRepository[`autoCompleteRepository()`]
 |Domain service class
 |nominate a method on a domain service to be used for looking up instances of the domain object
 
@@ -38,56 +38,56 @@ xref:rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditerService`]
 |override the method name to use on the auto-complete repository
 
 
-|xref:rgant.adoc#_rgant-DomainObject_bounded[`bounded()`]
+|xref:../rgant/rgant.adoc#_rgant-DomainObject_bounded[`bounded()`]
 |`true`, `false` +
 (`false`)
 |Whether the number of instances of this domain class is relatively small (a "bounded" set), such that instances could be selected from a drop-down list box or similar.
 
-|xref:rgant.adoc#_rgant-DomainObject_createdLifecycleEvent[`created-` +
+|xref:../rgant/rgant.adoc#_rgant-DomainObject_createdLifecycleEvent[`created-` +
 `LifecycleEvent()`]
 |subtype of `ObjectCreatedEvent` +
 (`ObjectCreatedEvent.Default`)
-|the event type to be posted to the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] whenever an instance is created
+|the event type to be posted to the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] whenever an instance is created
 
-|xref:rgant.adoc#_rgant-DomainObject_editing[`editing()`]
+|xref:../rgant/rgant.adoc#_rgant-DomainObject_editing[`editing()`]
 |`AS_CONFIGURED`, `ENABLED`, `DISABLED` +
 (`AS_CONFIGURED`)
 |whether the object's properties and collections can be edited or not (ie whether the instance should be considered to be immutable)
 
 
-|xref:rgant.adoc#_rgant-DomainObject_mixinMethod[`mixinMethod()`]
+|xref:../rgant/rgant.adoc#_rgant-DomainObject_mixinMethod[`mixinMethod()`]
 |Method name within the mixin
 |How to recognize the "reserved" method name, meaning that the mixin's own name will be inferred from the mixin type.
 Typical examples are "exec", "execute", "invoke", "apply" and so on.
 The default "reserved" method name is `$$`.
 
 
-|xref:rgant.adoc#_rgant-DomainObject_nature[`nature()`]
+|xref:../rgant/rgant.adoc#_rgant-DomainObject_nature[`nature()`]
 |`NOT_SPECIFIED`, `JDO_ENTITY`, `EXTERNAL_ENTITY`, `INMEMORY_ENTITY`, `MIXIN`, `VIEW_MODEL` (`NOT_SPECIFIED`)
 |whether the domain object logically is an entity (part of the domain layer) or is a view model (part of the application layer); or is a mixin.  If an entity, indicates how its persistence is managed.
 
 
-|xref:rgant.adoc#_rgant-DomainObject_objectType[`objectType()`]
+|xref:../rgant/rgant.adoc#_rgant-DomainObject_objectType[`objectType()`]
 |(none, which implies fully qualified class name)
 |specify an alias for the domain class used to uniquely identify the object both within the Apache Isis runtime and externally
 
 
-|xref:rgant.adoc#_rgant-DomainObject_persistedLifecycleEvent[`persisted-` +
+|xref:../rgant/rgant.adoc#_rgant-DomainObject_persistedLifecycleEvent[`persisted-` +
 `LifecycleEvent()`]
 |subtype of `ObjectPersistedEvent` +
 (`ObjectPersistedEvent.Default`)
-|the event type to be posted to the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] whenever an instance has just been persisted
+|the event type to be posted to the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] whenever an instance has just been persisted
 
-|xref:rgant.adoc#_rgant-DomainObject_persistingLifecycleEvent[`persisting-` +
+|xref:../rgant/rgant.adoc#_rgant-DomainObject_persistingLifecycleEvent[`persisting-` +
 `LifecycleEvent()`]
 |subtype of `ObjectPersistingEvent` +
 (`ObjectPersistingEvent.Default`)
-|the event type to be posted to the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] whenever an instance is about to be persisted
+|the event type to be posted to the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] whenever an instance is about to be persisted
 
-|xref:rgant.adoc#_rgant-DomainObject_publishing[`publishing()`]
+|xref:../rgant/rgant.adoc#_rgant-DomainObject_publishing[`publishing()`]
 |`AS_CONFIGURED`, `ENABLED`, `DISABLED` +
 (`AS_CONFIGURED`)
-|whether changes to the object should be published to the registered xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`].
+|whether changes to the object should be published to the registered xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`].
 
 
 |`publishing-` +
@@ -95,23 +95,23 @@ The default "reserved" method name is `$$`.
 |subtype of `PublishingPayloadFactory-` `ForObject` (none)
 |specifies that a custom implementation of `PublishingPayloadFactoryForObject` be used to create the (payload of the) published event representing the change to the object
 
-|xref:rgant.adoc#_rgant-DomainObject_removingLifecycleEvent[`removing-` +
+|xref:../rgant/rgant.adoc#_rgant-DomainObject_removingLifecycleEvent[`removing-` +
 `LifecycleEvent()`]
 |subtype of `ObjectRemovingEvent` +
 (`ObjectRemovingEvent.Default`)
-|the event type to be posted to the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] whenever an instance is about to be deleted
+|the event type to be posted to the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] whenever an instance is about to be deleted
 
-|xref:rgant.adoc#_rgant-DomainObject_updatedLifecycleEvent[`updated-` +
+|xref:../rgant/rgant.adoc#_rgant-DomainObject_updatedLifecycleEvent[`updated-` +
 `LifecycleEvent()`]
 |subtype of `ObjectUpdatedEvent` +
 (`ObjectUpdatedEvent.Default`)
-|the event type to be posted to the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] whenever an instance has just been updated
+|the event type to be posted to the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] whenever an instance has just been updated
 
-|xref:rgant.adoc#_rgant-DomainObject_updatingLifecycleEvent[`updating-` +
+|xref:../rgant/rgant.adoc#_rgant-DomainObject_updatingLifecycleEvent[`updating-` +
 `LifecycleEvent()`]
 |subtype of `ObjectUpdatingEvent` +
 (`ObjectUpdatingEvent.Default`)
-|the event type to be posted to the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] whenever an instance is about to be updated
+|the event type to be posted to the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] whenever an instance is about to be updated
 
 |===
 

[27/58] [abbrv] isis git commit: more on ugfun.adoc - identifiers, programming model for services etc

[da...@apache.org]

more on ugfun.adoc - identifiers, programming model for services etc


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/2ca2ea18
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/2ca2ea18
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/2ca2ea18

Branch: refs/heads/wip
Commit: 2ca2ea184da8d9ef1a65e22139d0a2030290a2c2
Parents: 2f2714c
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Mon Apr 17 14:51:19 2017 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Thu Apr 20 09:09:30 2017 +0100

----------------------------------------------------------------------
 .../guides/ugfun/_ugfun_building-blocks.adoc    |   4 +-
 .../ugfun/_ugfun_building-blocks_events.adoc    |  61 +-----
 ...un_building-blocks_events_domain-events.adoc |  40 ++++
 ...building-blocks_events_lifecycle-events.adoc |  32 +++
 ..._ugfun_building-blocks_events_ui-events.adoc |  28 +++
 .../_ugfun_building-blocks_identifiers.adoc     |   4 +-
 ...lding-blocks_identifiers_title-and-icon.adoc |  24 ++-
 .../ugfun/_ugfun_building-blocks_modules.adoc   |   9 +
 ...ugfun_programming-model_domain-entities.adoc | 129 ++++++++----
 ...ugfun_programming-model_domain-services.adoc | 209 +++++++++----------
 ...gfun_programming-model_view-models_jaxb.adoc |  10 +
 ..._programming-model_view-models_non-jaxb.adoc |  12 ++
 ..._ugfun_ui-hints_object-titles-and-icons.adoc |  12 +-
 13 files changed, 350 insertions(+), 224 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/2ca2ea18/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks.adoc
index 8c61796..fe81aa7 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks.adoc
@@ -16,8 +16,6 @@ include::_ugfun_building-blocks_object-members.adoc[leveloffset=+1]
 
 include::_ugfun_building-blocks_events.adoc[leveloffset=+1]
 
-include::_ugfun_building-blocks_identifiers.adoc[leveloffset=+1]
-
-nclude::_ugfun_building-blocks_modules.adoc[leveloffset=+1]
+include::_ugfun_building-blocks_modules.adoc[leveloffset=+1]
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/2ca2ea18/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_events.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_events.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_events.adoc
index ded8c28..1746b40 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_events.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_events.adoc
@@ -11,7 +11,7 @@ These events enable other domain services (possibly in other modules) to influen
 [TIP]
 ====
 It is also possible to simulate the rendering of a domain object by way of the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`].
-This
+This allows business rules to be enforced for programmatic interactions between objects.
 ====
 
 To receive the events, the domain service should subscribe to the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`], and implement an appropriately annotated method to receive the events.
@@ -20,60 +20,7 @@ The framework has several categories of events: domain events, UI events and lif
 These are explored in the sections below.
 
 
-
-== Domain Events
-Domain events are fired for each object member (property, collection or action).
-
-By default, rendering a property causes a `PropertyDomainEvent` to be fired, though the xref:../rgant/rgant.adoc#_rgant_Property_domainEvent[`@Property#domainEvent()`] attribute allows a custom subclass to be specified if necessary.
-Similarly, rendering a collection causes a `CollectionDomainEvent` to be fired, and rendering an action causes an `ActionDomainEvent` to be fired.
-
-In fact, each event can be fired up to five times, with the event's `getEventPhase()` method indicating to the subscriber the phase:
-
-* *hide* phase allows the subscriber to hide the member
-
-* *disable* phase allows the subscriber to disable the member. +
-
-For a property this makes it read-only; for an action this makes it "greyed out".
-(Collections are implicitly read-only).
-
-* *validate* phase allows the subscriber to validate the proposed change.
-
-For a property this means validating the proposed new value of the property; for an action this means validating the action parameter arguments.
-For example, a referential integrity restrict could be implemented here.
-
-* *executing* phase is prior to the actual property edit/action invocation, allowing the subscriber to perform side-effects. +
-
-For example, a cascade delete could be implemented here.
-
-* *executed* phase is after the actual property edit/action invocation. +
-+
-For example, a business audit event could be implemented here.
-
-
-For more details on the actual domain event classes, see the xref:../rgcms/rgcms.adoc#_rgcms_classes_domainevent[domain event] section of the relevant reference guide.
-
-
-
-
-== UI Events
-
-To allow the end-user to distinguish one domain object from another, it is rendered with a title and an icon.
-The icon informally identifies the type of the domain object, while the title identifies the instance.
-The title is not formally required to be a unique identify the object within its type, but it needs to be "unique enough" that a human user is able to distinguish one instance from another.
-
-Sometimes it's helpful for the icon to represent more than just the object's type; it might also indicate the state of an object.
-For example, a shipped `Order` might have a slightly different icon to a yet-to-be-shipped `Order`; or an overdue `Loan` might be distinguished separately from a
-
-Customisable icons
-
-and optionally with custom CSS
-Each domain object is rendered with a
-NOTE: FIXME
-
-
-For more details on the actual domain event classes, see the xref:../rgcms/rgcms.adoc#_rgcms_classes_uievent[UI event] section of the relevant reference guide.
-
-
-== Lifecycle Events
-
+include::_ugfun_building-blocks_events_domain-events.adoc[leveloffset=+1]
+include::_ugfun_building-blocks_events_ui-events.adoc[leveloffset=+1]
+include::_ugfun_building-blocks_events_lifecycle-events.adoc[leveloffset=+1]
 

http://git-wip-us.apache.org/repos/asf/isis/blob/2ca2ea18/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_events_domain-events.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_events_domain-events.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_events_domain-events.adoc
new file mode 100644
index 0000000..9911cc6
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_events_domain-events.adoc
@@ -0,0 +1,40 @@
+[[_ugfun_building-blocks_events_domain-events]]
+= Domain Events
+: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/
+
+
+Domain events are fired for each object member (property, collection or action).
+
+By default, rendering a property causes a `PropertyDomainEvent` to be fired, though the xref:../rgant/rgant.adoc#_rgant_Property_domainEvent[`@Property#domainEvent()`] attribute allows a custom subclass to be specified if necessary.
+Similarly, rendering a collection causes a `CollectionDomainEvent` to be fired, and rendering an action causes an `ActionDomainEvent` to be fired.
+
+In fact, each event can be fired up to five times, with the event's `getEventPhase()` method indicating to the subscriber the phase:
+
+* *hide* phase allows the subscriber to hide the member
+
+* *disable* phase allows the subscriber to disable the member. +
+
+For a property this makes it read-only; for an action this makes it "greyed out".
+(Collections are implicitly read-only).
+
+* *validate* phase allows the subscriber to validate the proposed change.
+
+For a property this means validating the proposed new value of the property; for an action this means validating the action parameter arguments.
+For example, a referential integrity restrict could be implemented here.
+
+* *executing* phase is prior to the actual property edit/action invocation, allowing the subscriber to perform side-effects. +
+
+For example, a cascade delete could be implemented here.
+
+* *executed* phase is after the actual property edit/action invocation. +
++
+For example, a business audit event could be implemented here.
+
+
+For more details on the actual domain event classes, see the xref:../rgcms/rgcms.adoc#_rgcms_classes_domainevent[domain event] section of the relevant reference guide.
+
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2ca2ea18/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_events_lifecycle-events.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_events_lifecycle-events.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_events_lifecycle-events.adoc
new file mode 100644
index 0000000..5e9d666
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_events_lifecycle-events.adoc
@@ -0,0 +1,32 @@
+[[_ugfun_building-blocks_events_lifecycle-events]]
+= Lifecycle Events
+: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/
+
+
+Lifecycle events allow domain object subscribers to listen for changes to the persistence state of domain entities, and act accordingly.
+
+[NOTE]
+====
+Lifecycle events are _not_ fired for view models.
+====
+
+
+The lifecycle events supported are:
+
+* object created - just instantiated
+* updated loaded - just retrieved from the database
+* object persisting - object about to be inserted into the database
+* object persisted - object just inserted into the database
+* object updating - object about to be updated
+* object updated - object just updated
+* object removing - object about to be deleted from the database
+
+There is no lifecycle event for object creating because the framework doesn't know about newly created objects until they have been created; and there is no lifecycle event for obejcts removed because it is not valid to "touch" a domain entity once deleted.
+
+
+For example, if annotated with xref:../rgant/rgant.adoc#_rgant_DomainObject_updatingLifecycleEvent[`@DomainObjectLayout#updatingLifecycleEvent()`], the appropriate (subclass of) `ObjectUpdatingEvent` will be emitted.
+ Similarly for xref:../rgant/rgant.adoc#_rgant_DomainObjectLayout_iconUiEvent[`iconUiEvent()`] and xref:../rgant/rgant.adoc#_rgant_DomainObjectLayout_cssClassUiEvent[`cssClassUiEvent()`].
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2ca2ea18/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_events_ui-events.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_events_ui-events.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_events_ui-events.adoc
new file mode 100644
index 0000000..3a88ce3
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_events_ui-events.adoc
@@ -0,0 +1,28 @@
+[[_ugfun_building-blocks_events_ui-events]]
+= UI Events
+: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/
+
+
+As explained xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_identifiers_title-and-icon[earlier], to allow the end-user to distinguish one domain object from another, it is rendered with a title and an icon.
+
+Normally the code to return title and icon of an object is part of the domain object's implementation.
+However, UI events allow this title and icon to be provided instead by a subscriber.
+
+If annotated with xref:../rgant/rgant.adoc#_rgant_DomainObjectLayout_titleUiEvent[`@DomainObjectLayout#titleUiEvent()`], the appropriate (subclass of) `TitleUiEvent` will be emitted.
+ Similarly for xref:../rgant/rgant.adoc#_rgant_DomainObjectLayout_iconUiEvent[`iconUiEvent()`] and xref:../rgant/rgant.adoc#_rgant_DomainObjectLayout_cssClassUiEvent[`cssClassUiEvent()`].
+
+This can be particularly useful for xref:../ugfun/ugfun.adoc#_ugfun_programming-model_view-models_jaxb[JAXB-style view models] which are used as DTOs and so must have no dependencies on the rest of the Apache Isis framework.
+
+
+
+[TIP]
+====
+Details on how to actually implement titles and icons, see
+xref:../ugfun/ugfun.adoc#_ugfun_ui-hints_object-titles-and-icons[here].
+====
+
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2ca2ea18/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_identifiers.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_identifiers.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_identifiers.adoc
index c0bc698..1117f2b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_identifiers.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_identifiers.adoc
@@ -5,8 +5,10 @@
 :_imagesdir: images/
 
 
-NOTE: FIXME
+The Apache Isis framework actively tracks the identity of each domain object.
+This identity is represented to the end-user in human-readable form so that they know which object they are interacting with, and is also used and is available internally/for integrations.
 
+This section explores these two related concepts.
 
 
 include::_ugfun_building-blocks_identifiers_title-and-icon.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/2ca2ea18/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_identifiers_title-and-icon.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_identifiers_title-and-icon.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_identifiers_title-and-icon.adoc
index 356abe8..f9446ff 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_identifiers_title-and-icon.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_identifiers_title-and-icon.adoc
@@ -5,23 +5,31 @@
 :_imagesdir: images/
 
 
-NOTE: FIXME
+To allow the end-user to distinguish one domain object from another, it is rendered with a title and an icon.
+The icon informally identifies the type of the domain object, while the title identifies the instance.
 
+== Title
 
+The title of a domain object is shown in several places: as the main heading for an object; as a link text for an object referencing another object, and also in tables representing collections of objects.
 
-To allow the end-user to distinguish one domain object from another, it is rendered with a title and an icon.
-The icon informally identifies the type of the domain object, while the title identifies the instance.
 The title is not formally required to be a unique identify the object within its type, but it needs to be "unique enough" that a human user is able to distinguish one instance from another.
 
+The title is usually just a simple string, but the framework also allows for the title to be translated into different locales.
+
+== Icon
+
 Sometimes it's helpful for the icon to represent more than just the object's type; it might also indicate the state of an object.
 For example, a shipped `Order` might have a slightly different icon to a yet-to-be-shipped `Order`; or an overdue `Loan` might be distinguished separately from a
 
-Customisable icons
+== CSS Class
 
-and optionally with custom CSS
-Each domain object is rendered with a
-NOTE: FIXME
+In addition to the title and icon, it is also possible for a domain object to provide a CSS class hint.
+In conjunction with xref:../ugvw/ugvw.adoc#_ugvw_customisation_tweaking-css-classes[customized CSS] this can be used to apply arbitrary styling; for example each object could be rendered in a page with a different background colour.
 
 
-For more details on the actual domain event classes, see the xref:../rgcms/rgcms.adoc#_rgcms_classes_uievent[UI event] section of the relevant reference guide.
+[TIP]
+====
+Details on how to actually write titles, icons and CSS classes can be found
+xref:../ugfun/ugfun.adoc#_ugfun_ui-hints_object-titles-and-icons[here].
+====
 

http://git-wip-us.apache.org/repos/asf/isis/blob/2ca2ea18/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_modules.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_modules.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_modules.adoc
index 40dbca0..dfe956e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_modules.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_modules.adoc
@@ -11,5 +11,14 @@ By convention there will be a single top-level package corresponding to the modu
 For example, the (non-ASF) link:https://github.com/incodehq/incode-module-document[Document module] (part of the link:http://catalog.incode.org[Incode Catalog]) has a top-level package of `org.incode.module.document`.
 Within the module there may be various subpackages, but its the module defines the namespace.
 
+The bootstrapping of Apache Isis also relies on module classes.
+(Currently) the only role of these classes is to identify a fully qualified package name, for example `org.incode.modules.document`.
+The framework then performs classpath scanning across all such packages to locate any domain entities provided by that module (though some modules have no entities), all domain services provided by the module (every module is likely to define at least one), and also any fixture scripts provided by the module.
+
+[TIP]
+====
 In the same way that the Java module act as a namespace for domain objects, it's good practice to map domain entities to their own (database) schemas.
+====
+
+
 

http://git-wip-us.apache.org/repos/asf/isis/blob/2ca2ea18/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-entities.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-entities.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-entities.adoc
index ad2bd72..3102fe6 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-entities.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-entities.adoc
@@ -5,12 +5,14 @@
 :_imagesdir: images/
 
 
-
 Entities are persistent domain objects, with their persistence handled by JDO/DataNucleus.
 As such, they are mapped to a persistent object store, typically an RDBMS, with DataNucleus taking care of both lazy loading and also the persisting of modified ("dirty") objects.
 
 Domain entities are generally decorated with both DataNucleus and Apache Isis annotations.
-The following is typical:
+Let's look at some of the most commonly-used annotations.
+
+To start with, entities are flagged as being "persistence capable", indicating how JDO/DataNucleus should manage their identity:
+
 
 [source,java]
 ----
@@ -27,63 +29,116 @@ The following is typical:
         strategy= VersionStrategy.DATE_TIME,
         column="version"
 )
-@javax.jdo.annotations.Queries({
-        @javax.jdo.annotations.Query(                                           // <6>
-                name = "findByName",
-                value = "SELECT "
-                        + "FROM domainapp.modules.simple.dom.impl.SimpleObject "
-                        + "WHERE name.indexOf(:name) >= 0 ")
-})
-@javax.jdo.annotations.Unique(name="SimpleObject_name_UNQ", members = {"name"}) // <7>
-@DomainObject(                                                                  // <8>
+@DomainObject(                                                                  // <6>
         objectType = "simple.SimpleObject"
 )
+public class SimpleObject { ... }
+----
+<1> The `@PersistenceCapable` annotation indicates that this is an entity to DataNucleus.
+The DataNucleus enhancer acts on the bytecode of compiled entities, injecting lazy loading and dirty object tracking functionality.
+Enhanced entities end up also implementing the `javax.jdo.spi.PersistenceCapable` interface.
+<2> Indicates how identifiers for the entity are handled.
+Using `DATASTORE` means that a DataNucleus is responsible for assigning the value (rather than the application).
+<3> Specifies the RDBMS database schema and table name for this entity will reside.
+The schema should correspond with the module in which the entity resides.
+The table will default to the entity name if omitted.
+<4> For entities that are using `DATASTORE` identity, indicates how the id will be assigned.
+A common strategy is to allow the database to assign the id, for example using an identity column or a sequence.
+<5> The `@Version` annotation is useful for optimistic locking; the strategy indicates what to store in the `version` column.
+<6> The `@DomainObject` annotation identifies the domain object to Apache Isis (not DataNucleus).
+It isn't necessary to include this annotation -- at least, not for entities -- but it is nevertheless recommended.
+In particular, its strongly recommended that the `objectType` (which acts like an alias to the concrete domain class) is specified; note that it corresponds to the schema/table for DataNucleus' `@PersistenceCapable` annotation.
+
+
+All domain entities will have some sort of mandatory key properties.
+The example below is a very simple case, where the entity is identified by a `name` property:
+
+[source,java]
+----
+...
+@javax.jdo.annotations.Unique(name="SimpleObject_name_UNQ", members = {"name"}) // <1>
 public class SimpleObject
-             implements Comparable<SimpleObject> {                              // <9>
+             implements Comparable<SimpleObject> {                              // <2>
 
-    public SimpleObject(final String name) {                                    // <10>
+    public SimpleObject(final String name) {                                    // <3>
         setName(name);
     }
 
-    ...
+    @javax.jdo.annotations.Column(allowsNull="false", length=50)                // <4>
+    @lombok.Getter @lombok.Setter
+    private String name;
 
     @Override
     public String toString() {
-        return ObjectContracts.toString(this, "name");                          // <11>
+        return ObjectContracts.toString(this, "name");                          // <5>
     }
     @Override
     public int compareTo(final SimpleObject other) {
-        return ObjectContracts.compare(this, other, "name");                    // <9>
+        return ObjectContracts.compare(this, other, "name");                    // <2>
     }
 }
 ----
-<1> The `@PersistenceCapable` annotation indicates that this is an entity to DataNucleus.
-The DataNucleus enhancer acts on the bytecode of compiled entities, injecting lazy loading and dirty object tracking functionality.
-Enhanced entities end up also implementing the `javax.jdo.spi.PersistenceCapable` interface.
-<2> Indicates how identifiers for the entity are handled.
-Using `DATASTORE` means that a DataNucleus is responsible for assigning the value (rather than the application).
-<3> Specifies the RDBMS database schema and table name for this entity will reside.
-The schema should correspond with the module in which the entity resides.
-The table will default to the entity name if omitted.
-<4> For entities that are using `DATASTORE` identity, indicates how the id will be assigned.
-A common strategy is to allow the database to assign the id, for example using an identity column or a sequence.
-<5> The `@Version` annotation is useful for optimistic locking; the strategy indicates what to store in the `version` column.
-<6> The `@Query` annotation (usually several of them, nested within a `@Queries` annotation) defines queries using JDOQL.
-DataNucleus provides several APIs for defining queries, including entirely programmatic and type-safe APIs; but JDOQL is very similar to SQL and so easily learnt.
-<7> DataNucleus will automatically add a unique index to the primary surrogate id (discussed above), but additional alternative keys can be defined using the `@Unique` annotation.
+<1> DataNucleus will automatically add a unique index to the primary surrogate id (discussed above), but additional alternative keys can be defined using the `@Unique` annotation.
 In the example above, the "name" property is assumed to be unique.
-<8> The `@DomainObject` annotation identifies the domain object to Apache Isis (not DataNucleus).
-It isn't necessary to include this annotation -- at least, not for entities -- but it is nevertheless recommended.
-In particular, its strongly recommended that the `objectType` (which acts like an alias to the concrete domain class) is specified; note that it corresponds to the schema/table for DataNucleus' `@PersistenceCapable` annotation.
-<9> Although not required, we strongly recommend that all entities are naturally `Comparable`.
+<2> Although not required, we strongly recommend that all entities are naturally `Comparable`.
 This then allows parent/child relationships to be defined using ``SortedSet``s; RDBMS after all are set-oriented.
 The `ObjectContracts` utility class provided by Apache Isis makes it easy to implement the `compareTo()` method, but you can also just use an IDE to generate an implementation or roll your own.
-<10> Chances are that some of the properties of the entity will be mandatory, for example any properties that represent an alternate unique key to the entity.
+<3> Chances are that some of the properties of the entity will be mandatory, for example any properties that represent an alternate unique key to the entity.
 In regular Java programming we would represent this using a constructor that defines these mandatory properties, and in Apache Isis/DataNucleus we can likewise define such a constructor.
 When DataNucleus rehydrates domain entities from the database at runtime, it actually requires a no-arg constructor (it then sets all state reflectively).
 However, there is no need to provide such a no-arg constructor; it is added by the enhancer process.
-<11> The `ObjectContracts` utility class also provides assistance for `toString()`, useful when debugging in an IDE.
+<4> The `name` property itself, using Lombok to generate the getter and setter.
+The `@Column` annotation specifies the length of the column in the RDBMS; this metadata is read by JDO/DataNucleus but Apache Isis itself also infers that the property is mandatory and its length from this annotation.
+<5> The `ObjectContracts` utility class also provides assistance for `toString()`, useful when debugging in an IDE.
+
+It's also common for domain entities to have queries annotated on them.
+These are used by repository domain services to query for instances of the entity:
+
+[source,java]
+----
+...
+@javax.jdo.annotations.Queries({
+    @javax.jdo.annotations.Query(                                           // <1>
+        name = "findByName",                                                // <2>
+        value = "SELECT "                                                   // <3>
+                + "FROM domainapp.modules.simple.dom.impl.SimpleObject "    // <4>
+                + "WHERE name.indexOf(:name) >= 0 ")                        // <5>
+})
+...
+public class SimpleObject { ... }
+----
+<1> There may be several `@Query` annotations, nested within a `@Queries` annotation) defines queries using JDOQL.
+<2> Defines the name of the query.
+<3> The definition of the query, using JDOQL syntax.
+<4> The fully-qualified class name.
+Must correspond to the class on which the annotation is defined (the framework checks this automatically on bootstrapping).
+<5> In this particular query, is an implementation of a LIKE "name%" query.
+
+DataNucleus provides several APIs for defining queries, including entirely programmatic and type-safe APIs; but JDOQL is very similar to SQL and so easily learnt.
+
+The corresponding repository method for the above query is:
+
+[source,java]
+----
+public List<SimpleObject> findByName(String name) {
+    return repositoryService.allMatches(                                    // <1>
+            new QueryDefault<>(SimpleObject.class,                          // <2>
+                        "findByName",                                       // <3>
+                        "name",                                             // <4>
+                        name);
+}
+
+@javax.inject.Inject
+RepositoryService repositoryService;
+----
+<1> The `RepositoryService` is a generic facade over the JDO/DataNucleus API, provided by the Apache Isis framework.
+<2> Specifies the class that is annotated with `@Query`
+<3> Corresponds to the `@Query#name()` attribute
+<4> Corresponds to the `:name` parameter in the query JDOQL string
 
 
-NOTE: FIXME - xref the ugodn guide for other mappings of persistent entities.
+[TIP]
+====
+See the xref:../ugodn/ugodn.adoc#[DataNucleus objectstore guide] for further information on annotating domain entities.
+====
 

http://git-wip-us.apache.org/repos/asf/isis/blob/2ca2ea18/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services.adoc
index 68f8919..4a322f3 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services.adoc
@@ -5,10 +5,8 @@
 :_imagesdir: images/
 
 
-This section looks at the programming conventions of writing your own domain services.
+This section looks at the programming model for writing your own domain services.
 
-''''
-''''
 
 [[__ugfun_building-blocks_domain-services_organizing-services]]
 == Organizing Services
@@ -17,45 +15,30 @@ In larger applications we have found it worthwhile to ensure that our domain ser
 
 The application provides the `@DomainService(nature=...)` annotation that helps distinguish some of these responsibilities:
 
-- `VIEW` indicates that the actions should appear both on the menu and also be used as contributions
-- `VIEW_MENU_ONLY` indicates that the actions should appear on the menu
-- `VIEW_CONTRIBUTIONS_ONLY` indicates that the actions should not appear on the menu
-- `DOMAIN` indicates that the actions are for other domain objects to invoke (either directly or indirectly through the event bus), but in any case should not be rendered at all in the UI
+* `VIEW_MENU_ONLY` indicates that the actions should appear on the menu of the xref:../ugvw/ugvw.adoc#[Wicket viewer], and as top-level actions for the REST API provided by the xref:../ugvro/ugvro.adoc#[Restful Objects viewer]
 
-NOTE: FIXME - deprecate any mention of VIEW_CONTRIBUTIONS_ONLY
+* `DOMAIN` indicates that the actions are for other domain objects to invoke (either directly or indirectly through the event bus), but in any case should not be rendered at all in the UI
 
-Pulling all the above together, here are our suggestions as to how you should organize your domain services.
-
-NOTE: FIXME - instead, xref to progamming model sections
+* `VIEW_REST_ONLY` indicates that the actions should appear in the REST API provided by the xref:../ugvro/ugvro.adoc#[Restful Objects viewer], but not rendered by the xref:../ugvw/ugvw.adoc#[Wicket viewer].
 
+There are also two other natures that should be considered "deprecated":
 
+* `VIEW_CONTRIBUTIONS_ONLY` which indicates that the actions should be contributed as actions to its action parameters. +
++
+This feature is deprecated because xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_types-of-domain-objects_mixins[mixins] are equivalent in functionality with a simpler programming model.
 
+* `VIEW` combines both `VIEW_MENU_ONLY` and the deprecated `VIEW_CONTRIBUTIONS_ONLY`.
 
-== Prototyping
+If the domain service nature is not specified (or is left to its default, `VIEW`), then the service's actions will appear in the UI.
 
 While for long-term maintainability we do recommend the naming conventions described xref:../ugfun/ugfun.adoc#__ugfun_building-blocks_domain-services_organizing-services[above], you can get away with far fewer services when just prototyping a domain.
-
-If the domain service nature is not specified (or is left to its default, `VIEW`), then the service's actions will
-appear in the UI both as menu items _and_ as contributions (and the service can of course be injected into other domain objects for programmatic invocation).
-
 Later on it is easy enough to refactor the code to tease apart the different responsibilities.
 
+Pulling all the above together, here are our suggestions as to how you should organize your domain services.
 
 
-
-
-''''
-''''
-
-
-== Typical Implementation
-
-Domain services are generally singletons that are automatically injected into other domain services.
-A very common usage is as a repository (to find/locate existing entities) or as a factory (to create new instances of entities).
-But services can also be exposed in the UI as top-level menus; and services are also used as a bridge to access technical resources (eg rendering a document object as a PDF).
-
-The Apache Isis framework itself also provides a large number of number of domain services, catalogued in the xref:../rgsvc/rgsvc.adoc#[Domain Services Reference Guide].
-Some of these are APIs (intended to be called by your application's own domain objects) and some are SPIs (implemented by your application and called by the framework, customising the way it works).
+[[__ugfun_programming-model_domain-services_menu]]
+== Menu
 
 The following is a typical menu service:
 
@@ -86,25 +69,10 @@ public class SimpleObjectMenu {
     SimpleObjectRepository simpleObjectRepository;              // <4>
 }
 ----
-<1> The (Apache Isis) `@DomainService` annotation is used to identify the class as a domain service.
-Apache Isis scans the classpath looking for classes with this annotation, so there very little configuration other than to tell the framework which packages to scan underneath.
-The `VIEW_MENU_ONLY` nature indicates that this service's actions should be exposed as menu items.
-<2> The (Apache Isis) `@DomainServiceLayout` annotation provides UI hints.
-In the example above the menu is named "Simple Objects" (otherwise it would have defaulted to "Simple Object Menu", based on the class name, while the `menuOrder` attribute determines the order of the menu with respect to other menu services.
-<3> The `findByName` method is annotated with various Apache Isis annotations (`@Action`, `@ActionLayout` and `@MemberOrder`) and is itself rendered in the UI as a "Find By Name" menu item underneath the "Simple Objects" menu.
-The implementation delegates to an `SimpleObjectRepository` service, which is injected.
-<4> The `javax.inject.Inject` annotation instructs Apache Isis framework to inject the `SimpleObjectRepository` service into this domain object.
-The framework can inject into not just other domain services but will also automatically into domain entities and view models.
-There is further discussion of service injection xref:../ugfun/ugfun.adoc#_ugfun_programming-model_inject-services[below].
-
-
-
-''''
-''''
 
 
 
-[[__ugfun_building-blocks_domain-services_factory-and-repository]]
+[[__ugfun_programming-model_domain-services_factory-and-repository]]
 == Factory and Repository
 
 The factory/repository uses an injected xref:../rgsvc/rgsvc.adoc#_rgsvc_api_RepositoryService[`RepositoryService`] to both instantiate new objects and to query the database for existing objects of a given entity type.  It is not visible in UI, rather other services delegate to it.
@@ -153,21 +121,26 @@ We suggest naming such classes `XxxMenu`, eg:
 
 [source,java]
 ----
-@DomainService(
-    nature = NatureOfService.VIEW_MENU_ONLY                     // <1>
+@DomainService(                                                 // <1>
+    nature = NatureOfService.VIEW_MENU_ONLY
 )
-@DomainServiceLayout(
-        named = "Customers",                                    // <2>
+@DomainServiceLayout(                                           // <2>
+        named = "Customers",
         menuBar = DomainServiceLayout.MenuBar.PRIMARY,
         menuOrder = "10"
 )
 public class CustomerMenu {
+
     @Action(
             semantics = SemanticsOf.SAFE
     )
+    @ActionLayout(bookmarking = BookmarkPolicy.AS_ROOT)
     @MemberOrder( sequence = "1" )
-    public List<Customer> findCustomerBy...(...) {
-        return customerRepository.findCustomerBy(...);          // <3>
+    public List<Customer> findByName(                           // <3>
+            @ParameterLayout(named="Name")
+            final String name
+    ) {
+        return customerRepository.findByName(name);             // <4>
     }
 
     @Action(
@@ -180,114 +153,127 @@ public class CustomerMenu {
 
     @Action(
             semantics = SemanticsOf.SAFE,
-            restrictTo = RestrictTo.PROTOTYPING
+            restrictTo = RestrictTo.PROTOTYPING                 // <5>
     )
     @MemberOrder( sequence = "99" )
-    public List<Customer> allCustomers() {
-        return customerRepository.allBankMandates();
+    public List<Customer> listAll() {
+        return customerRepository.listAll();
     }
 
     @Inject
-    protected CustomerRepository customerRepository;
+    protected CustomerRepository customerRepository;            // <4>
 }
 ----
-<1> the service's actions should be rendered as menu items
-<2> specifies the menu name.  All services with the same menu name will be displayed on the same menu, with separators between
-<3> delegates to an injected repository.
+<1> The (Apache Isis) xref:../rgant/rgant.adoc#_rgant_DomainService[`@DomainService`] annotation is used to identify the class as a domain service.
+Apache Isis scans the classpath looking for classes with this annotation, so there very little configuration other than to tell the framework which packages to scan underneath.
+The `VIEW_MENU_ONLY` nature indicates that this service's actions should be exposed as menu items.
+<3> The xref:../rgant/rgant.adoc#_rgant_DomainServiceLayout[`@DomainServiceLayout`] annotation provides UI hints.
+The menu is named "Customers" (otherwise it would have defaulted to "Customer Menu", based on the class name, while the xref:../rgant/rgant.adoc#_rgant_DomainServiceLayout_menuOrder[`menuOrder`] attribute determines the order of the menu with respect to other menu services.
+<3> The `findByName` method is annotated with various Apache Isis annotations (xref:../rgant/rgant.adoc#_rgant_Action[`@Action`], xref:../rgant/rgant.adoc#_rgant_ActionLayout[`@ActionLayout`] and xref:../rgant/rgant.adoc#_rgant_MemberOrder[`@MemberOrder`] and is itself rendered in the UI as a "Find By Name" menu item underneath the "Simple Objects" menu.
+<4> the action implementation delegates to an injected repository.
+The framework can inject into not just other domain services but will also automatically into domain entities and view models.
+There is further discussion of service injection xref:../ugfun/ugfun.adoc#_ugfun_programming-model_inject-services[below].
+<4> xref:../rgant/rgant.adoc#_rgant_Action_restrictTo[Prototype] actions are rendered only in prototyping mode.
+A "list all" action such as this can be useful when exploring the domain with a small dataset.
 
 Not every action on the repository need to be delegated to of course (the above example does but only because it is very simple).
 
 [TIP]
 ====
-Note also that while there's nothing to stop `VIEW_MENU` domain services being injected into other domain objects and interacted with programmatically, we recommend against it.  Instead, inject the underlying repository.  If there is additional business logic, then consider introducing a further `DOMAIN`-scoped service and call that instead.
+While there's nothing to stop `VIEW_MENU` domain services being injected into other domain objects and interacted with programmatically, we recommend against it.
+Instead, inject the underlying repository.
+If there is additional business logic, then consider introducing a further `DOMAIN`-scoped service and call that instead.
 ====
 
 
 
-[[__ugfun_building-blocks_domain-services_contributions]]
-== Contributions (deprecated)
 
+[[__ugfun_building-blocks_domain-services_event-subscribers]]
+== Event Subscribers
 
-Services can contribute either actions, properties or collections, based on the type of their parameters.
+Domain services acting as event subscribers can subscribe to xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_events_domain-events[domain], xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_events_ui-events[UI] and xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_events_lifecycle-events[lifecycle] events, influencing the rendering and behaviour of other objects.
 
-[TIP]
-====
-Contributed services can instead be implemented as
-xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_mixins[mixins].
-As such, contributed services should be considered as deprecated.
-====
+All subscribers must subscribe to the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`]; as this amounts to a few lines of boilerplate it's easiest to inherit from the convenience `AbstractSubscriber` class.
 
-We suggest naming such classes `XxxContributions`, eg:
+We suggest naming such classes `XxxSubscriptions`, for example:
 
 [source,java]
 ----
 @DomainService(
-    nature=NatureOfService.VIEW_CONTRIBUTIONS_ONLY              // <1>
+    nature=NatureOfService.DOMAIN                               // <1>
 )
 @DomainServiceLayout(
     menuOrder="10",
     name="...",
 }
-public class OrderContributions {
-    @Action(semantics=SemanticsOf.SAFE)
-    @ActionLayout(contributed=Contributed.AS_ASSOCIATION)       // <2>
-    @CollectionLayout(render=RenderType.EAGERLY)
-    public List<Order> orders(Customer customer) {              // <3>
-        return container.allMatches(...);
+public class CustomerOrderSubscriptions
+                    extends AbstractSubscriber {                // <2>
+
+    @org.axonframework.eventhandling.annotation.EventHandler    // <3>
+    @com.google.common.eventbus.Subscribe                       // <3>
+    public void on(final Customer.DeletedEvent ev) {            // <4>
+        Customer customer = ev.getSource();
+        orderRepository.delete(customer);
     }
 
     @Inject
-    CustomerRepository customerRepository;
+    OrderRepository orderRepository;
 }
 ----
-<1> the service's actions should be contributed to the entities of the parameters of those actions
-<2> contributed as an association, in particular as a collection because returns a `List<T>`.
-<3> Only actions with a single argument can be contributed as associations
-
-More information about contributions can be found xref:../ugfun/ugfun.adoc#_ugfun_how-tos_contributed-members[here].  More information
-about using contributions and mixins to keep your domain application decoupled can be found xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_contributions[here] and xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_mixins[here].
-
-
+<1> subscriptions do not appear in the UI at all, so should use the domain nature of service
+<2> subclass from the `AbstractSubscriber` convenience superclass
+<3> The framework supports two different implementations for the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] - Axon framework and Guava.
+Subscribers should use the appropriate annotation type depending on the implementation chosen (or as shown here, use both annotations).
+<4> the parameter type of the method corresponds to the event emitted on the event bus.
+The actual method name does not matter (though it must have `public` visibility).
 
 
-[[__ugfun_building-blocks_domain-services_event-subscribers]]
-== Event Subscribers
+[[__ugfun_building-blocks_domain-services_contributions]]
+== Contributions (deprecated)
 
-NOTE: FIXME - use AbstractSubscriber, need to show how to subscribe with event service bus...
+Services can contribute either actions, properties or collections, based on the type of their parameters.
 
-Event subscribers can both veto interactions (hiding members, disabling members or validating changes), or can react to interactions (eg action invocation or property edit).
+[WARNING]
+====
+Contributed services should be considered a deprecated feature.
+Instead, contribute the behaviour using xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_mixins[mixins].
+====
 
-We suggest naming such classes `XxxSubscriptions`, eg:
+We suggest naming such classes `XxxContributions`, eg:
 
 [source,java]
 ----
 @DomainService(
-    nature=NatureOfService.DOMAIN                       // <1>
+    nature=NatureOfService.VIEW_CONTRIBUTIONS_ONLY              // <1>
 )
 @DomainServiceLayout(
     menuOrder="10",
     name="...",
 }
-public class CustomerOrderSubscriptions {
-    @com.google.common.eventbus.Subscribe
-    public void on(final Customer.DeletedEvent ev) {
-        Customer customer = ev.getSource();
-        orderRepository.delete(customer);
+public class OrderContributions {
+    @Action(semantics=SemanticsOf.SAFE)
+    @ActionLayout(contributed=Contributed.AS_ASSOCIATION)       // <2>
+    @CollectionLayout(render=RenderType.EAGERLY)
+    public List<Order> orders(Customer customer) {              // <3>
+        return container.allMatches(...);
     }
+
     @Inject
-    OrderRepository orderRepository;
+    CustomerRepository customerRepository;
 }
 ----
-<1> subscriptions do not appear in the UI at all, so should use the domain nature of service
-
+<1> the service's actions should be contributed to the entities of the parameters of those actions
+<2> contributed as an association, in particular as a collection because returns a `List<T>`.
+<3> Only actions with a single argument can be contributed as associations
 
+More information about contributions can be found xref:../ugfun/ugfun.adoc#_ugfun_how-tos_contributed-members[here].  More information
+about using contributions and mixins to keep your domain application decoupled can be found xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_contributions[here] and xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_mixins[here].
 
 
-''''
-''''
 
 
 
+[[__ugfun_building-blocks_domain-services_scoped-services]]
 == Scoped services
 
 By default all domain services are considered to be singletons, and thread-safe.
@@ -309,10 +295,11 @@ The framework provides a number of request-scoped services, include a xref:../rg
 
 
 
-== Registering domain services
+[[__ugfun_building-blocks_domain-services_registering]]
+== Registering
 
-The easiest way to register domain services is using xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`] to specify the modules
-which contain xref:../rgant/rgant.adoc#_rgant-DomainService[`@DomainService`]-annotated classes.
+The easiest way to register domain services with the framework is to use an xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`].
+This specifies the modules which contain xref:../rgant/rgant.adoc#_rgant-DomainService[`@DomainService`]-annotated classes.
 
 For example:
 
@@ -359,25 +346,17 @@ Examples of framework-provided services (as defined in the applib) include clock
 
 
 
+[[__ugfun_building-blocks_domain-services_initialization]]
 == Initialization
 
 Services can optionally declare lifecycle callbacks to initialize them (when the app is deployed) and to shut them down (when the app is undeployed).
 
 An Apache Isis session _is_ available when initialization occurs (so services can interact with the object store, for example).
 
-
-The framework will call any `public` method annotated with xref:../rgant/rgant.adoc#_rgant-PostConstruct[`@PostConstruct`] with either no arguments of an argument of type `Map<String,String>`
-
-or
-
+The framework will call any `public` method annotated with xref:../rgant/rgant.adoc#_rgant-PostConstruct[`@PostConstruct`] with either no arguments of an argument of type `Map<String,String>`.
 In the latter case, the framework passes in the configuration (`isis.properties` and any other component-specific configuration files).
 
-
 Shutdown is similar; the framework will call any method annotated with xref:../rgant/rgant.adoc#_rgant-PreDestroy[`@PreDestroy`].
 
 
 
-== The getId() method
-
-Optionally, a service may provide a xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_getId[`getId()`] method.  This method returns a logical identifier for a service, independent of its implementation.
-

http://git-wip-us.apache.org/repos/asf/isis/blob/2ca2ea18/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_jaxb.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_jaxb.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_jaxb.adoc
new file mode 100644
index 0000000..8eadadb
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_jaxb.adoc
@@ -0,0 +1,10 @@
+[[_ugfun_programming-model_view-models_jaxb]]
+= JAXB View Models
+
+: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/
+
+
+
+NOTE: FIXME

http://git-wip-us.apache.org/repos/asf/isis/blob/2ca2ea18/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_non-jaxb.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_non-jaxb.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_non-jaxb.adoc
new file mode 100644
index 0000000..2069a9a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_non-jaxb.adoc
@@ -0,0 +1,12 @@
+[[_ugfun_programming-model_view-models_non-jaxb]]
+= Non-JAXB View Models
+
+: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/
+
+
+
+
+NOTE: FIXME
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2ca2ea18/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_object-titles-and-icons.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_object-titles-and-icons.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_object-titles-and-icons.adoc
index 1c8663a..a1a3301 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_object-titles-and-icons.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_object-titles-and-icons.adoc
@@ -5,11 +5,14 @@
 :_imagesdir: images/
 
 
-In Apache Isis every object is identified to the user by a title (label) and an icon.  This is shown in several places: as the main heading for an object; as a link text for an object referencing another object, and also in tables representing collections of objects.
+In Apache Isis every object is identified to the user by a title (label) and an icon.
+This is shown in several places: as the main heading for an object; as a link text for an object referencing another object, and also in tables representing collections of objects.
 
-The icon is often the same for all instances of a particular class, but it's also possible for an individual instance to return a custom icon.  This could represent the state of that object (eg a shipped order, say, or overdue library book).
+The icon is often the same for all instances of a particular class, but it's also possible for an individual instance to return a custom icon.
+This could represent the state of that object (eg a shipped order, say, or overdue library book).
 
-It is also possible for an object to provide a CSS class hint.  In conjunction with xref:../ugvw/ugvw.adoc#_ugvw_customisation_tweaking-css-classes[customized CSS] this can be used to apply arbitrary styling; for example each object could be rendered in a page with a different background colour.
+It is also possible for an object to provide a CSS class hint.
+In conjunction with xref:../ugvw/ugvw.adoc#_ugvw_customisation_tweaking-css-classes[customized CSS] this can be used to apply arbitrary styling; for example each object could be rendered in a page with a different background colour.
 
 
 == Object Title
@@ -79,6 +82,9 @@ NOTE: FIXME - see xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_title[`title(
 
 
 
+NOTE: FIXME -
+For more details on the actual UI event classes, see the xref:../rgcms/rgcms.adoc#_rgcms_classes_uievent[UI event] section of the relevant reference guide.
+
 
 == Object Icon
 

[36/58] [abbrv] isis git commit: object titles and icons; fixing links

[da...@apache.org]

object titles and icons; fixing links


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/85b1e70b
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/85b1e70b
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/85b1e70b

Branch: refs/heads/wip
Commit: 85b1e70b20db42fb7e576d38d5df995eb1279eab
Parents: 2ca2ea1
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Mon Apr 17 17:44:16 2017 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Thu Apr 20 09:09:30 2017 +0100

----------------------------------------------------------------------
 .../guides/cgcom/_cgcom-applying-patches.adoc   |  90 ---
 .../guides/cgcom/_cgcom_applying-patches.adoc   |  90 +++
 .../cgcom/_cgcom_release-process-prereqs.adoc   |   2 +-
 .../src/main/asciidoc/guides/cgcom/cgcom.adoc   |   4 +-
 .../asciidoc/guides/dg/_dg_asciidoc-syntax.adoc |   4 +-
 .../asciidoc/guides/dg/_dg_building-isis.adoc   |   2 +-
 .../asciidoc/guides/dg/_dg_ide_intellij.adoc    |   4 +-
 .../asciidoc/guides/dg/_dg_project-lombok.adoc  |   2 +-
 .../asciidoc/guides/rgcms/_rgcms_classes.adoc   |   2 +-
 .../guides/rgcms/_rgcms_classes_layout.adoc     |   2 +-
 .../rgcms/_rgcms_classes_mixins_Object.adoc     |   2 +-
 ..._rgfis_spi_MessageBrokerServiceInternal.adoc |   2 +-
 ...s_spi_PersistenceSessionServiceInternal.adoc |   2 +-
 ...is_spi_TransactionStateProviderInternal.adoc |   2 +-
 .../guides/rgsvc/_rgsvc_api_LayoutService.adoc  |   2 +-
 .../guides/rgsvc/_rgsvc_api_SwaggerService.adoc |   2 +-
 .../guides/rgsvc/_rgsvc_metadata-api.adoc       |   2 +-
 .../rgsvc/_rgsvc_spi_ContentMappingService.adoc |   2 +-
 .../rgsvc/_rgsvc_spi_GridSystemService.adoc     |   4 +-
 .../guides/rgsvc/_rgsvc_spi_HintStore.adoc      |   2 +-
 ...placing-default-service-implementations.adoc |   2 +-
 ...gbtb_programming-model_custom-validator.adoc |   2 +-
 ...cks_types-of-domain-objects_view-models.adoc |  24 +-
 .../guides/ugfun/_ugfun_programming-model.adoc  |   8 +-
 .../_ugfun_programming-model_collections.adoc   |   2 +-
 ...ugfun_programming-model_domain-services.adoc | 359 +----------
 ...ing-model_domain-services_contributions.adoc |  48 ++
 ...model_domain-services_event-subscribers.adoc |  46 ++
 ...ng-model_domain-services_initialization.adoc |  19 +
 ..._programming-model_domain-services_menu.adoc |  91 +++
 ...del_domain-services_organizing-services.adoc |  33 +
 ...mming-model_domain-services_registering.adoc |  56 ++
 ..._domain-services_repository-and-factory.adoc |  46 ++
 ...g-model_domain-services_scoped-services.adoc |  23 +
 .../ugfun/_ugfun_programming-model_mixins.adoc  | 305 +--------
 ...ramming-model_mixins_contributed-action.adoc |  29 +
 ...ing-model_mixins_contributed-collection.adoc |  38 ++
 ...mming-model_mixins_contributed-property.adoc |  35 ++
 ...mming-model_mixins_contributed-services.adoc |  46 ++
 ..._programming-model_mixins_inferred-name.adoc |  45 ++
 ...ming-model_mixins_nested-static-classes.adoc |  78 +++
 ...ramming-model_mixins_programmatic-usage.adoc |  26 +
 .../_ugfun_programming-model_properties.adoc    |   2 +-
 .../_ugfun_programming-model_view-models.adoc   | 629 +------------------
 ...ugfun_programming-model_view-models_dto.adoc |  69 ++
 ...ing-model_view-models_dto_dto-consumers.adoc |  32 +
 ...g-model_view-models_dto_generating-xsds.adoc | 176 ++++++
 ...amming-model_view-models_dto_versioning.adoc | 106 ++++
 ...gfun_programming-model_view-models_jaxb.adoc |  62 +-
 ...models_jaxb_referencing-domain-entities.adoc |  65 ++
 ..._programming-model_view-models_non-jaxb.adoc |  69 +-
 ..._ugfun_ui-hints_object-titles-and-icons.adoc | 252 +++++++-
 ...nts-and-tips_overriding-jdo-annotations.adoc |   2 +-
 .../ugsec/_ugsec_usage-by-isis-viewers.adoc     |   4 +-
 ...n-properties_suppressing-password-reset.adoc |   2 +-
 ...guration-properties_suppressing-sign-up.adoc |   2 +-
 .../guides/ugvw/_ugvw_layout_file-based.adoc    |   2 +-
 .../_migration-notes_1.11.0-to-1.12.0.adoc      |   2 +-
 .../_migration-notes_1.12.0-to-1.13.0.adoc      |   2 +-
 .../_migration-notes_1.9.0-to-1.10.0.adoc       |   3 +-
 .../asciidoc/pages/screencasts/screencasts.adoc |  12 +-
 61 files changed, 1646 insertions(+), 1432 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom-applying-patches.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom-applying-patches.adoc b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom-applying-patches.adoc
deleted file mode 100644
index a605202..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom-applying-patches.adoc
+++ /dev/null
@@ -1,90 +0,0 @@
-[[_cgcom_applying-patches]]
-= Applying Patches
-: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/
-:toc: right
-
-
-
-If a patch is received on a JIRA ticket, then it should be reviewed and applied. The commands are slightly different for diff files vs patch files.
-
-
-
-
-== Diff files
-
-If a diff file has been provided, then it can easily be applied using eGit's wizards (Eclipse's Git integration)\u2026
-
-NOTE: FIXME - this stuff needs fleshing out ...
-
-
-
-
-== Patch files
-
-If a patch file has been provided, then it can be applied using command line tools.
-
-=== Inspect the patch
-
-First, take a look at what changes are in the patch. You can do this easily with `git apply`
-
-[source,bash]
-----
-git apply --stat ISIS-xxx.patch
-----
-
-Note that this command does not apply the patch, but only shows you the stats about what it�\u20ac\u2122ll do. After peeking into the patch file with your favorite editor, you can see what the actual changes are.
-
-Next, you're interested in how troublesome the patch is going to be. Git allows you to test the patch before you actually apply it.
-
-[source,bash]
-----
-git apply --check ISIS-xxx.patch
-----
-
-If you don't get any errors, the patch has no conflicts. Otherwise you may see what trouble you�\u20ac\u2122ll run into.
-
-
-=== Apply a (clean) patch
-
-To apply a clean patch (adding the items and commit/signoff in a single step), use `git am`:
-
-[source,bash]
-----
-git am --signoff < ISIS-xxx.patch
-----
-
-This preserves the original author's commit message.
-
-However, this can fail if the patch file does not contain the original committers email address. In this case you will need to abort the `am` session:
-
-[source,bash]
-----
-git am abort
-----
-
-and continue on by applying a non-clean patch, as described next.
-
-
-
-=== Apply a (non-clean) patch
-
-If the patch does not apply cleanly, then the original authors commit message cannot be preserved. This sequence in this case is:
-
-[source,bash]
-----
-git apply ISIS-xxx.patch
-----
-
-Fix up any issues. The add and commit as usual
-
-[source,bash]
-----
-git add .
-git commit -am "<original authors' commit message>" --signoff
-----
-
-The `--signoff` simply adds a line to the commit message indicating you have signed off the commit.
-
-Information adapted from https://ariejan.net/2009/10/26/how-to-create-and-apply-a-patch-with-git/[this blog post] and http://wiki.eclipse.org/Jetty/Contributor/Contributing_Patches[this wiki page].
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_applying-patches.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_applying-patches.adoc b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_applying-patches.adoc
new file mode 100644
index 0000000..a605202
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_applying-patches.adoc
@@ -0,0 +1,90 @@
+[[_cgcom_applying-patches]]
+= Applying Patches
+: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/
+:toc: right
+
+
+
+If a patch is received on a JIRA ticket, then it should be reviewed and applied. The commands are slightly different for diff files vs patch files.
+
+
+
+
+== Diff files
+
+If a diff file has been provided, then it can easily be applied using eGit's wizards (Eclipse's Git integration)\u2026
+
+NOTE: FIXME - this stuff needs fleshing out ...
+
+
+
+
+== Patch files
+
+If a patch file has been provided, then it can be applied using command line tools.
+
+=== Inspect the patch
+
+First, take a look at what changes are in the patch. You can do this easily with `git apply`
+
+[source,bash]
+----
+git apply --stat ISIS-xxx.patch
+----
+
+Note that this command does not apply the patch, but only shows you the stats about what it�\u20ac\u2122ll do. After peeking into the patch file with your favorite editor, you can see what the actual changes are.
+
+Next, you're interested in how troublesome the patch is going to be. Git allows you to test the patch before you actually apply it.
+
+[source,bash]
+----
+git apply --check ISIS-xxx.patch
+----
+
+If you don't get any errors, the patch has no conflicts. Otherwise you may see what trouble you�\u20ac\u2122ll run into.
+
+
+=== Apply a (clean) patch
+
+To apply a clean patch (adding the items and commit/signoff in a single step), use `git am`:
+
+[source,bash]
+----
+git am --signoff < ISIS-xxx.patch
+----
+
+This preserves the original author's commit message.
+
+However, this can fail if the patch file does not contain the original committers email address. In this case you will need to abort the `am` session:
+
+[source,bash]
+----
+git am abort
+----
+
+and continue on by applying a non-clean patch, as described next.
+
+
+
+=== Apply a (non-clean) patch
+
+If the patch does not apply cleanly, then the original authors commit message cannot be preserved. This sequence in this case is:
+
+[source,bash]
+----
+git apply ISIS-xxx.patch
+----
+
+Fix up any issues. The add and commit as usual
+
+[source,bash]
+----
+git add .
+git commit -am "<original authors' commit message>" --signoff
+----
+
+The `--signoff` simply adds a line to the commit message indicating you have signed off the commit.
+
+Information adapted from https://ariejan.net/2009/10/26/how-to-create-and-apply-a-patch-with-git/[this blog post] and http://wiki.eclipse.org/Jetty/Contributor/Contributing_Patches[this wiki page].
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_release-process-prereqs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_release-process-prereqs.adoc b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_release-process-prereqs.adoc
index d2c9491..e54d9de 100644
--- a/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_release-process-prereqs.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_release-process-prereqs.adoc
@@ -14,7 +14,7 @@ This section (appendix) describes the prerequisites for the xref:../cgcom/cgcom.
 == Configure toolchains plugin
 
 Apache Isis releases are built using Java 7, enforced using the maven toolchains plugin.
-Ensure that Java 7 is installed and the toolchains plugin is configured, as described in the xref:__dg_building-isis_configure-maven-toolchains-plugin[contributors' guide].
+Ensure that Java 7 is installed and the toolchains plugin is configured, as described in the xref:../dg/dg.adoc#__dg_building-isis_configure-maven-toolchains-plugin[contributors' guide].
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/cgcom/cgcom.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/cgcom/cgcom.adoc b/adocs/documentation/src/main/asciidoc/guides/cgcom/cgcom.adoc
index d447116..3690a30 100644
--- a/adocs/documentation/src/main/asciidoc/guides/cgcom/cgcom.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/cgcom/cgcom.adoc
@@ -45,8 +45,8 @@ The remaining guides are:
 
 This guide provides guidance for Apache Isis' own committers.
 
-// for some reason this doesn't seem to include:: correctly; that said, it's incomplete anyway
-//include::_cgcom_applying-patches.adoc[leveloffset=+1]
+
+include::_cgcom_applying-patches.adoc[leveloffset=+1]
 
 include::_cgcom_merging-a-pull-request.adoc[leveloffset=+1]
 include::_cgcom_cutting-a-release.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc-syntax.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc-syntax.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc-syntax.adoc
index 345a56a..9c4d74c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc-syntax.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc-syntax.adoc
@@ -237,9 +237,9 @@ link:http://ciserver:8080[CI Server^]
 |Link to an external hyperlink, with `target=blank`
 
 |....
-xref:_markup-docs_background[background]
+xref:_markup-docs_background.adoc#[background]
 ....
-|xref:_markup-docs_background[background]
+|xref:_markup-docs_background.adoc#[background]
 |Cross-reference to section in same asciidoc document
 
 |....

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_building-isis.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_building-isis.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_building-isis.adoc
index 5f6335b..85ac50a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_building-isis.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_building-isis.adoc
@@ -141,7 +141,7 @@ For further reading, see:
 
 Apache Isis is compatible with Java 7 and Java 8.  For every-day use, the framework is usually compiled against Java 8.
 
-Releases however are xref:_cgcom_cutting-a-release[cut] using Java 7, leveraging the link:http://maven.apache.org/plugins/maven-toolchains-plugin/[Maven toolchains plugin]).
+Releases however are xref:../cgcom/cgcom.adoc#_cgcom_cutting-a-release[cut] using Java 7, leveraging the link:http://maven.apache.org/plugins/maven-toolchains-plugin/[Maven toolchains plugin]).
 
 Therefore install either/both of Java 7 JDK and Java 8 JDK.  Note that the JRE is _not_ sufficient.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_intellij.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_intellij.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_intellij.adoc
index c458e0f..19bf9a7 100644
--- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_intellij.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_intellij.adoc
@@ -181,7 +181,7 @@ On the *Annotation Processors* page, enable and adjust for the 'default' setting
 image::{_imagesdir}intellij-idea/040-other-settings-compiler/020-annotation-processor.png[width="700px"]
 
 This setting enables the generation of the `Q*` classes for DataNucleus type-safe queries, as well as being required
-for frameworks such as xref:_cg_ide_project-lombok[Project Lombok].
+for frameworks such as xref:../cgcom/cgcom.adoc#_cgcom_ide_project-lombok[Project Lombok].
 
 [NOTE]
 ====
@@ -483,7 +483,7 @@ If you hit an error of "duplicate classes":
 
 image::{_imagesdir}intellij-idea/060-troubleshooting/010-duplicate-classes.png[width="600px",link="{_imagesdir}intellij-idea/060-troubleshooting/010-duplicate-classes.png"]
 
-then make sure you have correctly configured the xref:_cg_ide_intellij_other-settings-compiler[annotation processor]
+then make sure you have correctly configured the xref:../dg/dg.adoc#_dg_ide_intellij_other-settings-compiler[annotation processor]
 settings.  Pay attention in particular to the "Production sources directory" and "Test sources directory", that these
 are set up correctly.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_project-lombok.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_project-lombok.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_project-lombok.adoc
index e3d7c4f..d8e86fe 100644
--- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_project-lombok.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_project-lombok.adoc
@@ -31,7 +31,7 @@ private String name;
 ----
 
 Under the covers it is implemented as an annotation processor; it basically hooks into the Java compiler
-so that it can emit additional bytecode (eg for the getter and setter).  See xref:_cg_ide_intellij_other-settings-compiler[here] for details of setting up in IntelliJ (Eclipse has very similar support).
+so that it can emit additional bytecode (eg for the getter and setter).  See xref:../dg/dg.adoc#_dg_ide_intellij_other-settings-compiler[here] for details of setting up in IntelliJ (Eclipse has very similar support).
 
 Apache Isis supports link:https://projectlombok.org/[Project Lombok], in that the annotations that would normally be placed on the getter (namely xref:../rgant/rgant.adoc#_rgant-Property[`Property`], xref:../rgant/rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`], xref:../rgant/rgant.adoc#_rgant-Collection[`@Collection`], xref:../rgant/rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`] and xref:../rgant/rgant.adoc#_rgant-MemberOrder[`@MemberOrder`]) can be placed on the field instead.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes.adoc
index 9aa0866..a5b318e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-This chapter describes the usage of various classes and interfaces that are not otherwise associated with xref:../rgsvc/rgsvc.adoc[domain services], xref:../ugvw/ugvw.adoc#_ugvw_layout[object layout] or xref:../rgcfg/rgcfg.adoc#_rgcfg[configuration].
+This chapter describes the usage of various classes and interfaces that are not otherwise associated with xref:../rgsvc/rgsvc.adoc#[domain services], xref:../ugvw/ugvw.adoc#_ugvw_layout[object layout] or xref:../rgcfg/rgcfg.adoc#_rgcfg[configuration].
 
 
 include::_rgcms_classes_AppManifest-bootstrapping.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_layout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_layout.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_layout.adoc
index 6f860f8..f215ef5 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_layout.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_layout.adoc
@@ -12,7 +12,7 @@ The `org.apache.isis.applib.layout` package defines a number of classes that all
 
 * common component classes, that capture the layout metadata for an object's properties, collections and actions.  These are bound (or associated) to the regions of the grid
 
-The framework provides an implementation of the grid classes modelled closely on link:http://getbootstrap.com[Bootstrap 3], along with xref:../ugvw/ugvw.adoc[Wicket viewer] components capable of rendering that grid system.  In principle it is
+The framework provides an implementation of the grid classes modelled closely on link:http://getbootstrap.com[Bootstrap 3], along with xref:../ugvw/ugvw.adoc#[Wicket viewer] components capable of rendering that grid system.  In principle it is
 also possible to extend the layout architecture for other grid systems.  The component classes, though, are intended to be reusable across all grid systems.
 
 The component classes, meanwhile, are broadly equivalent to the "layout" annotations (xref:../rgant/rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`], xref:../rgant/rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`], xref:../rgant/rgant.adoc#_rgant-ActionLayout[`@ActionLayout`] and xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout[`@DomainObjectLayout`]

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_mixins_Object.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_mixins_Object.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_mixins_Object.adoc
index db37617..77d5401 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_mixins_Object.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_mixins_Object.adoc
@@ -14,7 +14,7 @@ The framework provides a single mixin that contributes to simply `java.lang.Obje
 
 When a domain object is rendered the end-user can select different tabs, and for collections can sort the columns,
 navigate to second pages, or select different views of collections.  If the user revisits that object, the
-xref:../ugvw/ugvw.adoc[Wicket viewer] will remember these hints and render the domain object in the same state.  These
+xref:../ugvw/ugvw.adoc#[Wicket viewer] will remember these hints and render the domain object in the same state.  These
 rendering hints are also included if the user copies the URL using the anchor link (to right hand of the object's
 title).
 

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_MessageBrokerServiceInternal.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_MessageBrokerServiceInternal.adoc b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_MessageBrokerServiceInternal.adoc
index 88b89cc..2632371 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_MessageBrokerServiceInternal.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_MessageBrokerServiceInternal.adoc
@@ -39,6 +39,6 @@ The framework provides two implementations:
 
 * `MessageBrokerServiceInternalDefault` is provided by `isis-core-runtime`, and is used during normal use and integration tests
 
-* `MessageBrokerServiceInternalNoop` is provided as a fallback by `isis-core-metamodel`, and is provided to allow the xref:../rgmvn/rgmvn.adoc[maven plugin] to be bootstrapped without any "backend" database.
+* `MessageBrokerServiceInternalNoop` is provided as a fallback by `isis-core-metamodel`, and is provided to allow the xref:../rgmvn/rgmvn.adoc#[maven plugin] to be bootstrapped without any "backend" database.
 
 The `...Default` implementation takes priority over the `...Noop` implementation.

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_PersistenceSessionServiceInternal.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_PersistenceSessionServiceInternal.adoc b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_PersistenceSessionServiceInternal.adoc
index a7aee62..2427682 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_PersistenceSessionServiceInternal.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_PersistenceSessionServiceInternal.adoc
@@ -91,6 +91,6 @@ The framework provides two implementations:
 
 * `PersistenceSessionServiceInternalDefault` is provided by `isis-core-runtime`, and is used during normal use and integration tests
 
-* `PersistenceSessionServiceInternalNoop` is provided as a fallback by `isis-core-metamodel`, and is provided to allow the xref:../rgmvn/rgmvn.adoc[maven plugin] to be bootstrapped without any "backend" database.
+* `PersistenceSessionServiceInternalNoop` is provided as a fallback by `isis-core-metamodel`, and is provided to allow the xref:../rgmvn/rgmvn.adoc#[maven plugin] to be bootstrapped without any "backend" database.
 
 The `...Default` implementation takes priority over the `...Noop` implementation.

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_TransactionStateProviderInternal.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_TransactionStateProviderInternal.adoc b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_TransactionStateProviderInternal.adoc
index 655f8d0..c866f60 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_TransactionStateProviderInternal.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_TransactionStateProviderInternal.adoc
@@ -33,6 +33,6 @@ The framework provides two implementations:
 
 * `TransactionStateProviderInternalDefault` is provided by `isis-core-runtime`, and is used during normal use and integration tests
 
-* `TransactionStateProviderInternalNoop` is provided as a fallback by `isis-core-metamodel`, and is provided to allow the xref:../rgmvn/rgmvn.adoc[maven plugin] to be bootstrapped without any "backend" database.
+* `TransactionStateProviderInternalNoop` is provided as a fallback by `isis-core-metamodel`, and is provided to allow the xref:../rgmvn/rgmvn.adoc#[maven plugin] to be bootstrapped without any "backend" database.
 
 The `...Default` implementation takes priority over the `...Noop` implementation.

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_LayoutService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_LayoutService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_LayoutService.adoc
index 785354c..91f3890 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_LayoutService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_LayoutService.adoc
@@ -7,7 +7,7 @@
 
 
 The `LayoutService` provides the ability to obtain the XML layout for a single domain object or for all domain
-objects.  This functionality is surfaced through the user interface through a related xref:__rgsvc_api_LayoutService_related-mixins-and-menus[mixin and menu action].
+objects.  This functionality is surfaced through the user interface through a related xref:../rgsvc/rgsvc.adoc#__rgsvc_api_LayoutService_related-mixins-and-menus[mixin and menu action].
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_SwaggerService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_SwaggerService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_SwaggerService.adoc
index 03109c9..3bc5d7b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_SwaggerService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_SwaggerService.adoc
@@ -64,6 +64,6 @@ implementation of `SwaggerService` service is automatically registered and injec
 
 A `SwaggerServiceMenu` domain service provides a prototype action that enables the swagger spec to be downloaded from the Wicket viewer's UI.
 
-Apache Isis' xref:rgmvn.aod[Maven plugin] also provides a xref:../rgmvn/rgmvn.adoc#_rgmvn_swagger[swagger goal] which allows the spec file(s) to be generated at build time.  this then allows client-side stubs can then be generated in turn as part of a build pipeline.
+Apache Isis' xref:../rgmvn/rgmvn.adoc#[Maven plugin] also provides a xref:../rgmvn/rgmvn.adoc#_rgmvn_swagger[swagger goal] which allows the spec file(s) to be generated at build time.  this then allows client-side stubs can then be generated in turn as part of a build pipeline.
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_metadata-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_metadata-api.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_metadata-api.adoc
index 4c565f4..0ec8336 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_metadata-api.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_metadata-api.adoc
@@ -74,7 +74,7 @@ within the metamodel.
 |`SwaggerServiceDefault` +
 ``o.a.i.core`` +
 ``isis-core-metamodel``
-|A `SwaggerServiceMenu` domain service is also provided which enables the swagger spec to be downloaded.  Apache Isis' xref:../rgmvn/rgmvn.adoc[Maven plugin] also provides a xref:../rgmvn/rgmvn.adoc#_rgmvn_swagger[swagger goal] which allows the spec file(s) to be generated at build time (eg so that client-side stubs can then be generated in turn).
+|A `SwaggerServiceMenu` domain service is also provided which enables the swagger spec to be downloaded.  Apache Isis' xref:../rgmvn/rgmvn.adoc#[Maven plugin] also provides a xref:../rgmvn/rgmvn.adoc#_rgmvn_swagger[swagger goal] which allows the spec file(s) to be generated at build time (eg so that client-side stubs can then be generated in turn).
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_ContentMappingService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_ContentMappingService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_ContentMappingService.adoc
index b06c46b..416666a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_ContentMappingService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_ContentMappingService.adoc
@@ -42,7 +42,7 @@ public interface ContentMappingService {
 
 
 In versions prior to `v1.12.0`, this interface resided in a different package, internal to the
-xref:../ugvro/ugvro.adoc[Restful Objects] viewer, and defined a slightly different signature that used an internal enum:
+xref:../ugvro/ugvro.adoc#[Restful Objects] viewer, and defined a slightly different signature that used an internal enum:
 
 [source,java]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_GridSystemService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_GridSystemService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_GridSystemService.adoc
index 523bea6..ac28e20 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_GridSystemService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_GridSystemService.adoc
@@ -54,8 +54,8 @@ the service with the lowest xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_
 
 == Implementation
 
-The framework provides `GridSystemServiceBS3`, an implementation that encodes the bootstrap3 grid system.  (The framework
-also provides xref:../ugvw/ugvw.adoc[Wicket viewer] components that are capable of interpreting and rendering this metadata).
+The framework provides `GridSystemServiceBS3`, an implementation that encodes the bootstrap3 grid system.
+(The framework also provides xref:../ugvw/ugvw.adoc#[Wicket viewer] components that are capable of interpreting and rendering this metadata).
 
 
 == Registering the Services

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_HintStore.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_HintStore.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_HintStore.adoc
index 6d172d2..33f3e70 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_HintStore.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_HintStore.adoc
@@ -59,6 +59,6 @@ in the xref:../rgsvc/rgsvc.adoc#__rgsvc_intro_overriding-the-services[introducti
 
 == Related Services
 
-The xref:../ugvw/ugvw.adoc[Wicket viewer] exposes the xref:../rgcms/rgcms.adoc#__rgcms_classes_mixins_Object_clearHints["clear hints"]
+The xref:../ugvw/ugvw.adoc#[Wicket viewer] exposes the xref:../rgcms/rgcms.adoc#__rgcms_classes_mixins_Object_clearHints["clear hints"]
 mixin action that is for use by end-users of the application to clear any UI hints that have accumulated for a
 domain object.

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_replacing-default-service-implementations.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_replacing-default-service-implementations.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_replacing-default-service-implementations.adoc
index e3d29af..c4abd5d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_replacing-default-service-implementations.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_replacing-default-service-implementations.adoc
@@ -6,7 +6,7 @@
 
 
 
-The framework provides default implementations for many of the xref:../rgsvc/rgsvc.adoc[domain services].  This is convenient, but sometimes you will want to replace the default implementation with your own service implementation.
+The framework provides default implementations for many of the xref:../rgsvc/rgsvc.adoc#[domain services].  This is convenient, but sometimes you will want to replace the default implementation with your own service implementation.
 
 The trick is to use the xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] attribute, specifying a low number (typically `"1"`).
 

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_programming-model_custom-validator.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_programming-model_custom-validator.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_programming-model_custom-validator.adoc
index 3001a4a..732c0b9 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_programming-model_custom-validator.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_programming-model_custom-validator.adoc
@@ -17,7 +17,7 @@ You can also impose your own application-specific rules by installing your own m
 
 [TIP]
 ====
-Isis' xref:../rgmvn/rgmvn.adoc[Maven plugin] will also validate the domain object model during build time.
+Isis' xref:../rgmvn/rgmvn.adoc#[Maven plugin] will also validate the domain object model during build time.
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_types-of-domain-objects_view-models.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_types-of-domain-objects_view-models.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_types-of-domain-objects_view-models.adoc
index bc08274..07c8b50 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_types-of-domain-objects_view-models.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_types-of-domain-objects_view-models.adoc
@@ -132,31 +132,9 @@ In fact (as the xref:../ugbtb/ugbtb.adoc#_ugbtb_view-models_programming-model[pr
 It's also worth noting that it is also possible to download the XML (or XSD) straight from the UI, useful during development.
 The view model simply needs to implement the xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins_Dto[`Dto`] marker interface; the framework has xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins_Dto[mixins] that contribute the download actions to the view model.
 
-
-[[__ugfun_building-blocks_view-models_dtos_consumers]]
-=== DTO Consumers
-
-The actual consumers of DTOs will generally obtain the XML of the view models either by requesting the XML directly, eg using the xref:../ugvro/ugvro.adoc#[RestfulObjects viewer], or may have the XML sent to them asynchronously using an ESB such as Apache Camel.
-
-In the former case, the consumer requests the DTO by calling the REST API with the appropriate HTTP `Accept` header.
-An appropriate implementation of xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`] can then be used to return the appropriate DTO (as XML).
-
-For the latter case, one design is simply for the application to instantiate the view model, then call the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_JaxbService[`JaxbService`] to obtain its corresponding XML.  This can then be published onto the ESB, for example using an http://activemq.apache.org[Apache ActiveMQ (TM)] queue.
-
-However, rather than try to push all the data that might be needed by any of these external systems in a single XML event (which would require anticipating all the requirements, likely a hopeless task), a better design is to publish only the fact that something of note has changed - ie, that an action on a domain object has been invoked - and then let the consumers call back to obtain other information if required.
-This can once again be done by calling the REST API with an appropriate HTTP `Accept` header.
-
 [TIP]
 ====
-This is an example of the link:https://leanpub.com/camel-design-patterns[VETRO pattern] (validate, enrich, transform, route, operate).
-In our case we focus on the validation (to determine the nature of the inbound message, ie which action was invoked), and the enrich (callback to obtain a DTO with additional information required by the consumer).
+Details of how to consume such DTOs can be found xref:../ugfun/ugfun.adoc#_ugfun_programming-model_view-models_jaxb_dto-consumers[here].
 ====
 
-The (non-ASF) http://github.com/isisaddons/isis-module-publishmq[Isis addons' publishmq] module provides an out-of-the-box solution of this design.
-It provides an implementation of the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`], but which simply publishes instances of xref:../rgcms/rgcms.adoc#_rgcms_schema-aim[`ActionInvocationMemento`] to an ActiveMQ queue.
-Camel (or similar) can then be hooked up to consume these events from this queue, and use a processor to parse the action memento to determine what has changed on the source system.
-Thereafter, a subsequent Camel processor can then call back to the source - via the xref:../ugvro/ugvro.adoc[Restful Objects viewer] - to enrich the message with additional details using a DTO.
-
-
-
 

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model.adoc
index 98fcff1..f61440d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model.adoc
@@ -73,10 +73,6 @@ include::_ugfun_programming-model_domain-entities.adoc[leveloffset=+1]
 
 include::_ugfun_programming-model_domain-services.adoc[leveloffset=+1]
 
-include::_ugfun_programming-model_view-models.adoc[leveloffset=+1]
-
-include::_ugfun_programming-model_mixins.adoc[leveloffset=+1]
-
 include::_ugfun_programming-model_properties.adoc[leveloffset=+1]
 include::_ugfun_programming-model_collections.adoc[leveloffset=+1]
 include::_ugfun_programming-model_actions.adoc[leveloffset=+1]
@@ -85,6 +81,10 @@ include::_ugfun_programming-model_inject-services.adoc[leveloffset=+1]
 
 include::_ugfun_programming-model_properties-vs-parameters.adoc[leveloffset=+1]
 
+include::_ugfun_programming-model_view-models.adoc[leveloffset=+1]
+
+include::_ugfun_programming-model_mixins.adoc[leveloffset=+1]
+
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_collections.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_collections.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_collections.adoc
index 8a7aafe..62d5c20 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_collections.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_collections.adoc
@@ -25,7 +25,7 @@ This and other annotations can be used to specify if the association is bidirect
 
 Apache Isis recognises some of these annotations for JDO/DataNucleus and JAXB and infers some domain semantics from them (for example, the maximum allowable length of a string property).
 
-Unlike xref:../ugfun/ugfun.adoc#_ugfun_programming-model_properties[properties], the framework (at least, the xref:../ugvw/ugvw.adoc[Wicket viewer]) does not allow collections to be "edited".
+Unlike xref:../ugfun/ugfun.adoc#_ugfun_programming-model_properties[properties], the framework (at least, the xref:../ugvw/ugvw.adoc#[Wicket viewer]) does not allow collections to be "edited".
 Instead, xref:../ugfun/ugfun.adoc#_ugfun_programming-model_actions[action]s can be written that will modify the contents of the collection as a side-effect.
 For example, a `placeOrder(...)` action will likely add an `Order` to the `Customer#orders` collection.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services.adoc
index 4a322f3..cee3ce2 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services.adoc
@@ -7,356 +7,13 @@
 
 This section looks at the programming model for writing your own domain services.
 
-
-[[__ugfun_building-blocks_domain-services_organizing-services]]
-== Organizing Services
-
-In larger applications we have found it worthwhile to ensure that our domain services only act aligned with these responsibilities, employing a naming convention so that it is clear what the responsibilities of each domain service is.
-
-The application provides the `@DomainService(nature=...)` annotation that helps distinguish some of these responsibilities:
-
-* `VIEW_MENU_ONLY` indicates that the actions should appear on the menu of the xref:../ugvw/ugvw.adoc#[Wicket viewer], and as top-level actions for the REST API provided by the xref:../ugvro/ugvro.adoc#[Restful Objects viewer]
-
-* `DOMAIN` indicates that the actions are for other domain objects to invoke (either directly or indirectly through the event bus), but in any case should not be rendered at all in the UI
-
-* `VIEW_REST_ONLY` indicates that the actions should appear in the REST API provided by the xref:../ugvro/ugvro.adoc#[Restful Objects viewer], but not rendered by the xref:../ugvw/ugvw.adoc#[Wicket viewer].
-
-There are also two other natures that should be considered "deprecated":
-
-* `VIEW_CONTRIBUTIONS_ONLY` which indicates that the actions should be contributed as actions to its action parameters. +
-+
-This feature is deprecated because xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_types-of-domain-objects_mixins[mixins] are equivalent in functionality with a simpler programming model.
-
-* `VIEW` combines both `VIEW_MENU_ONLY` and the deprecated `VIEW_CONTRIBUTIONS_ONLY`.
-
-If the domain service nature is not specified (or is left to its default, `VIEW`), then the service's actions will appear in the UI.
-
-While for long-term maintainability we do recommend the naming conventions described xref:../ugfun/ugfun.adoc#__ugfun_building-blocks_domain-services_organizing-services[above], you can get away with far fewer services when just prototyping a domain.
-Later on it is easy enough to refactor the code to tease apart the different responsibilities.
-
-Pulling all the above together, here are our suggestions as to how you should organize your domain services.
-
-
-[[__ugfun_programming-model_domain-services_menu]]
-== Menu
-
-The following is a typical menu service:
-
-[source,java]
-----
-@DomainService(                                                 // <1>
-        nature = NatureOfService.VIEW_MENU_ONLY
-)
-@DomainServiceLayout(                                           // <2>
-        named = "Simple Objects",
-        menuOrder = "10"
-)
-public class SimpleObjectMenu {
-
-    ...
-
-    @Action(semantics = SemanticsOf.SAFE)
-    @ActionLayout(bookmarking = BookmarkPolicy.AS_ROOT)
-    @MemberOrder(sequence = "2")
-    public List<SimpleObject> findByName(                       // <3>
-            @ParameterLayout(named="Name")
-            final String name
-    ) {
-        return simpleObjectRepository.findByName(name);
-    }
-
-    @javax.inject.Inject
-    SimpleObjectRepository simpleObjectRepository;              // <4>
-}
-----
-
-
-
-[[__ugfun_programming-model_domain-services_factory-and-repository]]
-== Factory and Repository
-
-The factory/repository uses an injected xref:../rgsvc/rgsvc.adoc#_rgsvc_api_RepositoryService[`RepositoryService`] to both instantiate new objects and to query the database for existing objects of a given entity type.  It is not visible in UI, rather other services delegate to it.
-
-We suggest naming such classes `XxxRepository`, eg:
-
-
-[source,java]
-----
-@DomainService(
-    nature=NatureOfService.DOMAIN                               // <1>
-)
-public CustomerRepository {
-    public List<Customer> findCustomerBy...(...) {
-        return repositoyService.allMatches(...);
-    }
-    public Customer newCustomer(...) {
-        Customer Customer = container.newTransientInstance(Customer.class);
-        ...
-        persistIfNotAlready(Customer);
-        return Customer;
-    }
-    public List<Customer> allCustomers() {
-        return repositoryService.allInstances(Customer.class);
-    }
-    @Inject
-    RepositoryService repositoryService;
-}
-----
-<1> interacted with only programmatically by other objects in the domain layer.
-
-There is no need to annotate the actions; they are implicitly hidden because of the domain service's nature.
-
-
-[[__ugfun_building-blocks_domain-services_menu]]
-== Menu
-
-Menu services provide actions to be rendered on the menu.
-
-For the Wicket viewer, each service's actions appear as a collection of menu items of a named menu, and this menu is on one of the three menu bars provided by the Wicket viewer.  It is possible for more than one menu service's actions to appear on the same menu; a separator is shown between each.
-
-For the Restful Objects viewer, all menu services are shown in the services representation.
-
-We suggest naming such classes `XxxMenu`, eg:
-
-
-[source,java]
-----
-@DomainService(                                                 // <1>
-    nature = NatureOfService.VIEW_MENU_ONLY
-)
-@DomainServiceLayout(                                           // <2>
-        named = "Customers",
-        menuBar = DomainServiceLayout.MenuBar.PRIMARY,
-        menuOrder = "10"
-)
-public class CustomerMenu {
-
-    @Action(
-            semantics = SemanticsOf.SAFE
-    )
-    @ActionLayout(bookmarking = BookmarkPolicy.AS_ROOT)
-    @MemberOrder( sequence = "1" )
-    public List<Customer> findByName(                           // <3>
-            @ParameterLayout(named="Name")
-            final String name
-    ) {
-        return customerRepository.findByName(name);             // <4>
-    }
-
-    @Action(
-            semantics = SemanticsOf.NON_IDEMPOTENT
-    )
-    @MemberOrder( sequence = "3" )
-    public Customer newCustomer(...) {
-        return customerRepository.newCustomer(...);
-    }
-
-    @Action(
-            semantics = SemanticsOf.SAFE,
-            restrictTo = RestrictTo.PROTOTYPING                 // <5>
-    )
-    @MemberOrder( sequence = "99" )
-    public List<Customer> listAll() {
-        return customerRepository.listAll();
-    }
-
-    @Inject
-    protected CustomerRepository customerRepository;            // <4>
-}
-----
-<1> The (Apache Isis) xref:../rgant/rgant.adoc#_rgant_DomainService[`@DomainService`] annotation is used to identify the class as a domain service.
-Apache Isis scans the classpath looking for classes with this annotation, so there very little configuration other than to tell the framework which packages to scan underneath.
-The `VIEW_MENU_ONLY` nature indicates that this service's actions should be exposed as menu items.
-<3> The xref:../rgant/rgant.adoc#_rgant_DomainServiceLayout[`@DomainServiceLayout`] annotation provides UI hints.
-The menu is named "Customers" (otherwise it would have defaulted to "Customer Menu", based on the class name, while the xref:../rgant/rgant.adoc#_rgant_DomainServiceLayout_menuOrder[`menuOrder`] attribute determines the order of the menu with respect to other menu services.
-<3> The `findByName` method is annotated with various Apache Isis annotations (xref:../rgant/rgant.adoc#_rgant_Action[`@Action`], xref:../rgant/rgant.adoc#_rgant_ActionLayout[`@ActionLayout`] and xref:../rgant/rgant.adoc#_rgant_MemberOrder[`@MemberOrder`] and is itself rendered in the UI as a "Find By Name" menu item underneath the "Simple Objects" menu.
-<4> the action implementation delegates to an injected repository.
-The framework can inject into not just other domain services but will also automatically into domain entities and view models.
-There is further discussion of service injection xref:../ugfun/ugfun.adoc#_ugfun_programming-model_inject-services[below].
-<4> xref:../rgant/rgant.adoc#_rgant_Action_restrictTo[Prototype] actions are rendered only in prototyping mode.
-A "list all" action such as this can be useful when exploring the domain with a small dataset.
-
-Not every action on the repository need to be delegated to of course (the above example does but only because it is very simple).
-
-[TIP]
-====
-While there's nothing to stop `VIEW_MENU` domain services being injected into other domain objects and interacted with programmatically, we recommend against it.
-Instead, inject the underlying repository.
-If there is additional business logic, then consider introducing a further `DOMAIN`-scoped service and call that instead.
-====
-
-
-
-
-[[__ugfun_building-blocks_domain-services_event-subscribers]]
-== Event Subscribers
-
-Domain services acting as event subscribers can subscribe to xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_events_domain-events[domain], xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_events_ui-events[UI] and xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_events_lifecycle-events[lifecycle] events, influencing the rendering and behaviour of other objects.
-
-All subscribers must subscribe to the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`]; as this amounts to a few lines of boilerplate it's easiest to inherit from the convenience `AbstractSubscriber` class.
-
-We suggest naming such classes `XxxSubscriptions`, for example:
-
-[source,java]
-----
-@DomainService(
-    nature=NatureOfService.DOMAIN                               // <1>
-)
-@DomainServiceLayout(
-    menuOrder="10",
-    name="...",
-}
-public class CustomerOrderSubscriptions
-                    extends AbstractSubscriber {                // <2>
-
-    @org.axonframework.eventhandling.annotation.EventHandler    // <3>
-    @com.google.common.eventbus.Subscribe                       // <3>
-    public void on(final Customer.DeletedEvent ev) {            // <4>
-        Customer customer = ev.getSource();
-        orderRepository.delete(customer);
-    }
-
-    @Inject
-    OrderRepository orderRepository;
-}
-----
-<1> subscriptions do not appear in the UI at all, so should use the domain nature of service
-<2> subclass from the `AbstractSubscriber` convenience superclass
-<3> The framework supports two different implementations for the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] - Axon framework and Guava.
-Subscribers should use the appropriate annotation type depending on the implementation chosen (or as shown here, use both annotations).
-<4> the parameter type of the method corresponds to the event emitted on the event bus.
-The actual method name does not matter (though it must have `public` visibility).
-
-
-[[__ugfun_building-blocks_domain-services_contributions]]
-== Contributions (deprecated)
-
-Services can contribute either actions, properties or collections, based on the type of their parameters.
-
-[WARNING]
-====
-Contributed services should be considered a deprecated feature.
-Instead, contribute the behaviour using xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_mixins[mixins].
-====
-
-We suggest naming such classes `XxxContributions`, eg:
-
-[source,java]
-----
-@DomainService(
-    nature=NatureOfService.VIEW_CONTRIBUTIONS_ONLY              // <1>
-)
-@DomainServiceLayout(
-    menuOrder="10",
-    name="...",
-}
-public class OrderContributions {
-    @Action(semantics=SemanticsOf.SAFE)
-    @ActionLayout(contributed=Contributed.AS_ASSOCIATION)       // <2>
-    @CollectionLayout(render=RenderType.EAGERLY)
-    public List<Order> orders(Customer customer) {              // <3>
-        return container.allMatches(...);
-    }
-
-    @Inject
-    CustomerRepository customerRepository;
-}
-----
-<1> the service's actions should be contributed to the entities of the parameters of those actions
-<2> contributed as an association, in particular as a collection because returns a `List<T>`.
-<3> Only actions with a single argument can be contributed as associations
-
-More information about contributions can be found xref:../ugfun/ugfun.adoc#_ugfun_how-tos_contributed-members[here].  More information
-about using contributions and mixins to keep your domain application decoupled can be found xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_contributions[here] and xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_mixins[here].
-
-
-
-
-
-[[__ugfun_building-blocks_domain-services_scoped-services]]
-== Scoped services
-
-By default all domain services are considered to be singletons, and thread-safe.
-
-Sometimes though a service's lifetime is applicable only to a single request; in other words it is request-scoped.
-
-The CDI annotation xref:../rgant/rgant.adoc#_rgant-RequestScoped[`@javax.enterprise.context.RequestScoped`] is used to indicate this fact:
-
-[source,java]
-----
-@javax.enterprise.context.RequestScoped
-public class MyService extends AbstractService {
-    ...
-}
-----
-
-The framework provides a number of request-scoped services, include a xref:../rgsvc/rgsvc.adoc#_rgsvc_api_Scratchpad[`Scratchpad`] service query results caching through the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_QueryResultsCache[`QueryResultsCache`], and support for co-ordinating bulk actions through the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ActionInvocationContext[`ActionInvocationContext`] service.  See the xref:../rgsvc/rgsvc.adoc[domain services] reference guide for further details.
-
-
-
-
-[[__ugfun_building-blocks_domain-services_registering]]
-== Registering
-
-The easiest way to register domain services with the framework is to use an xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`].
-This specifies the modules which contain xref:../rgant/rgant.adoc#_rgant-DomainService[`@DomainService`]-annotated classes.
-
-For example:
-
-[source,ini]
-----
-public class MyAppManifest implements AppManifest {
-    public List<Class<?>> getModules() {
-        return Arrays.asList(
-                ToDoAppDomainModule.class,
-                ToDoAppFixtureModule.class,
-                ToDoAppAppModule.class,
-                org.isisaddons.module.audit.AuditModule.class);
-    }
-    ...
-}
-----
-
-will load all services in the packages underneath the four modules listed.
-
-An alternative (older) mechanism is to registered domain services in the `isis.properties` configuration file, under `isis.services` key (a comma-separated list); for example:
-
-[source,ini]
-----
-isis.services = com.mycompany.myapp.employee.Employees\,
-                com.mycompany.myapp.claim.Claims\,
-                ...
-----
-
-This will then result in the framework instantiating a single instance of each of the services listed.
-
-If all services reside under a common package, then the `isis.services.prefix` can specify this prefix:
-
-[source,ini]
-----
-isis.services.prefix = com.mycompany.myapp
-isis.services = employee.Employees,\
-                claim.Claims,\
-                ...
-----
-
-This is quite rare, however; you will often want to use default implementations of domain services that are provided by the framework and so will not reside under this prefix.
-
-Examples of framework-provided services (as defined in the applib) include clock, auditing, publishing, exception handling, view model support, snapshots/mementos, and user/application settings management; see the xref:../rgsvc/rgsvc.adoc[domain services] reference guide for further details.
-
-
-
-[[__ugfun_building-blocks_domain-services_initialization]]
-== Initialization
-
-Services can optionally declare lifecycle callbacks to initialize them (when the app is deployed) and to shut them down (when the app is undeployed).
-
-An Apache Isis session _is_ available when initialization occurs (so services can interact with the object store, for example).
-
-The framework will call any `public` method annotated with xref:../rgant/rgant.adoc#_rgant-PostConstruct[`@PostConstruct`] with either no arguments of an argument of type `Map<String,String>`.
-In the latter case, the framework passes in the configuration (`isis.properties` and any other component-specific configuration files).
-
-Shutdown is similar; the framework will call any method annotated with xref:../rgant/rgant.adoc#_rgant-PreDestroy[`@PreDestroy`].
-
+include::_ugfun_programming-model_domain-services_organizing-services.adoc[leveloffset=+1]
+include::_ugfun_programming-model_domain-services_repository-and-factory.adoc[leveloffset=+1]
+include::_ugfun_programming-model_domain-services_menu.adoc[leveloffset=+1]
+include::_ugfun_programming-model_domain-services_event-subscribers.adoc[leveloffset=+1]
+include::_ugfun_programming-model_domain-services_contributions.adoc[leveloffset=+1]
+include::_ugfun_programming-model_domain-services_scoped-services.adoc[leveloffset=+1]
+include::_ugfun_programming-model_domain-services_registering.adoc[leveloffset=+1]
+include::_ugfun_programming-model_domain-services_initialization.adoc[leveloffset=+1]
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_contributions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_contributions.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_contributions.adoc
new file mode 100644
index 0000000..107a550
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_contributions.adoc
@@ -0,0 +1,48 @@
+[[_ugfun_programming-model_domain-services_contributions]]
+= Contributions (deprecated)
+: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/
+
+
+
+Services can contribute either actions, properties or collections, based on the type of their parameters.
+
+[WARNING]
+====
+Contributed services should be considered a deprecated feature.
+Instead, contribute the behaviour using xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_mixins[mixins].
+====
+
+We suggest naming such classes `XxxContributions`, eg:
+
+[source,java]
+----
+@DomainService(
+    nature=NatureOfService.VIEW_CONTRIBUTIONS_ONLY              // <1>
+)
+@DomainServiceLayout(
+    menuOrder="10",
+    name="...",
+}
+public class OrderContributions {
+    @Action(semantics=SemanticsOf.SAFE)
+    @ActionLayout(contributed=Contributed.AS_ASSOCIATION)       // <2>
+    @CollectionLayout(render=RenderType.EAGERLY)
+    public List<Order> orders(Customer customer) {              // <3>
+        return container.allMatches(...);
+    }
+
+    @Inject
+    CustomerRepository customerRepository;
+}
+----
+<1> the service's actions should be contributed to the entities of the parameters of those actions
+<2> contributed as an association, in particular as a collection because returns a `List<T>`.
+<3> Only actions with a single argument can be contributed as associations
+
+More information about contributions can be found xref:../ugfun/ugfun.adoc#_ugfun_how-tos_contributed-members[here].  More information
+about using contributions and mixins to keep your domain application decoupled can be found xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_contributions[here] and xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_mixins[here].
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_event-subscribers.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_event-subscribers.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_event-subscribers.adoc
new file mode 100644
index 0000000..77c5040
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_event-subscribers.adoc
@@ -0,0 +1,46 @@
+[[_ugfun_programming-model_domain-services_event-subscribers]]
+= Event Subscribers
+: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/
+
+
+
+
+Domain services acting as event subscribers can subscribe to xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_events_domain-events[domain], xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_events_ui-events[UI] and xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_events_lifecycle-events[lifecycle] events, influencing the rendering and behaviour of other objects.
+
+All subscribers must subscribe to the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`]; as this amounts to a few lines of boilerplate it's easiest to inherit from the convenience `AbstractSubscriber` class.
+
+We suggest naming such classes `XxxSubscriptions`, for example:
+
+[source,java]
+----
+@DomainService(
+    nature=NatureOfService.DOMAIN                               // <1>
+)
+@DomainServiceLayout(
+    menuOrder="10",
+    name="...",
+}
+public class CustomerOrderSubscriptions
+                    extends AbstractSubscriber {                // <2>
+
+    @org.axonframework.eventhandling.annotation.EventHandler    // <3>
+    @com.google.common.eventbus.Subscribe                       // <3>
+    public void on(final Customer.DeletedEvent ev) {            // <4>
+        Customer customer = ev.getSource();
+        orderRepository.delete(customer);
+    }
+
+    @Inject
+    OrderRepository orderRepository;
+}
+----
+<1> subscriptions do not appear in the UI at all, so should use the domain nature of service
+<2> subclass from the `AbstractSubscriber` convenience superclass
+<3> The framework supports two different implementations for the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] - Axon framework and Guava.
+Subscribers should use the appropriate annotation type depending on the implementation chosen (or as shown here, use both annotations).
+<4> the parameter type of the method corresponds to the event emitted on the event bus.
+The actual method name does not matter (though it must have `public` visibility).
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_initialization.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_initialization.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_initialization.adoc
new file mode 100644
index 0000000..32544da
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_initialization.adoc
@@ -0,0 +1,19 @@
+[[_ugfun_programming-model_domain-services_initialization]]
+= Initialization
+: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/
+
+
+
+Services can optionally declare lifecycle callbacks to initialize them (when the app is deployed) and to shut them down (when the app is undeployed).
+
+An Apache Isis session _is_ available when initialization occurs (so services can interact with the object store, for example).
+
+The framework will call any `public` method annotated with xref:../rgant/rgant.adoc#_rgant-PostConstruct[`@PostConstruct`] with either no arguments of an argument of type `Map<String,String>`.
+In the latter case, the framework passes in the configuration (`isis.properties` and any other component-specific configuration files).
+
+Shutdown is similar; the framework will call any method annotated with xref:../rgant/rgant.adoc#_rgant-PreDestroy[`@PreDestroy`].
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_menu.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_menu.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_menu.adoc
new file mode 100644
index 0000000..64d3201
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_menu.adoc
@@ -0,0 +1,91 @@
+[[_ugfun_programming-model_domain-services_menu]]
+= Menu
+: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/
+
+
+Menu services provide actions to be rendered on the menu.
+
+For the Wicket viewer, each service's actions appear as a collection of menu items of a named menu, and this menu is on one of the three menu bars provided by the Wicket viewer.  It is possible for more than one menu service's actions to appear on the same menu; a separator is shown between each.
+
+For the Restful Objects viewer, all menu services are shown in the services representation.
+
+We suggest naming such classes `XxxMenu`, eg:
+
+
+[source,java]
+----
+@DomainService(                                                 // <1>
+    nature = NatureOfService.VIEW_MENU_ONLY
+)
+@DomainServiceLayout(                                           // <2>
+        named = "Customers",
+        menuBar = DomainServiceLayout.MenuBar.PRIMARY,
+        menuOrder = "10"
+)
+public class CustomerMenu {
+
+    @Action(
+            semantics = SemanticsOf.SAFE
+    )
+    @ActionLayout(bookmarking = BookmarkPolicy.AS_ROOT)
+    @MemberOrder( sequence = "1" )
+    public List<Customer> findByName(                           // <3>
+            @ParameterLayout(named="Name")                      // <4>
+            final String name
+    ) {
+        return customerRepository.findByName(name);             // <5>
+    }
+
+    @Action(
+            semantics = SemanticsOf.NON_IDEMPOTENT
+    )
+    @MemberOrder( sequence = "3" )
+    public Customer newCustomer(...) {
+        return customerRepository.newCustomer(...);
+    }
+
+    @Action(
+            semantics = SemanticsOf.SAFE,
+            restrictTo = RestrictTo.PROTOTYPING                 // <6>
+    )
+    @MemberOrder( sequence = "99" )
+    public List<Customer> listAll() {
+        return customerRepository.listAll();
+    }
+
+    @Inject
+    protected CustomerRepository customerRepository;            // <4>
+}
+----
+<1> The (Apache Isis) xref:../rgant/rgant.adoc#_rgant_DomainService[`@DomainService`] annotation is used to identify the class as a domain service.
+Apache Isis scans the classpath looking for classes with this annotation, so there very little configuration other than to tell the framework which packages to scan underneath.
+The `VIEW_MENU_ONLY` nature indicates that this service's actions should be exposed as menu items.
+<3> The xref:../rgant/rgant.adoc#_rgant_DomainServiceLayout[`@DomainServiceLayout`] annotation provides UI hints.
+The menu is named "Customers" (otherwise it would have defaulted to "Customer Menu", based on the class name, while the xref:../rgant/rgant.adoc#_rgant_DomainServiceLayout_menuOrder[`menuOrder`] attribute determines the order of the menu with respect to other menu services.
+<3> The `findByName` method is annotated with various Apache Isis annotations (xref:../rgant/rgant.adoc#_rgant_Action[`@Action`], xref:../rgant/rgant.adoc#_rgant_ActionLayout[`@ActionLayout`] and xref:../rgant/rgant.adoc#_rgant_MemberOrder[`@MemberOrder`] and is itself rendered in the UI as a "Find By Name" menu item underneath the "Simple Objects" menu.
+<4> The xref:../rgant/rgant.adoc#_rgant_ParameterLayout[`@ParameterLayout`] provides metadata for the parameter itself, in this case its name.
+<5> the action implementation delegates to an injected repository.
+The framework can inject into not just other domain services but will also automatically into domain entities and view models.
+There is further discussion of service injection xref:../ugfun/ugfun.adoc#_ugfun_programming-model_inject-services[below].
+<6> xref:../rgant/rgant.adoc#_rgant_Action_restrictTo[Prototype] actions are rendered only in prototyping mode.
+A "list all" action such as this can be useful when exploring the domain with a small dataset.
+
+[TIP]
+====
+Annotating action parameters with xref:../rgant/rgant.adoc#_rgant_ParameterLayout_named[`@ParameterLayout#named()`] can become somewhat tiresome.
+You can avoid doing this by configuring the (non-ASF) http://github.com/isisaddons/isis-metamodel-paraname8[Isis addons' paraname8] metamodel extension.
+====
+
+
+Not every action on the repository need to be delegated to of course (the above example does but only because it is very simple).
+
+[TIP]
+====
+While there's nothing to stop `VIEW_MENU` domain services being injected into other domain objects and interacted with programmatically, we recommend against it.
+Instead, inject the underlying repository.
+If there is additional business logic, then consider introducing a further `DOMAIN`-scoped service and call that instead.
+====
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_organizing-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_organizing-services.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_organizing-services.adoc
new file mode 100644
index 0000000..0ed0d44
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_organizing-services.adoc
@@ -0,0 +1,33 @@
+[[_ugfun_programming-model_domain-services_organizing-services]]
+= Organizing Services
+: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/
+
+
+
+In larger applications we have found it worthwhile to ensure that our domain services only act aligned with these responsibilities, employing a naming convention so that it is clear what the responsibilities of each domain service is.
+
+The application provides the `@DomainService(nature=...)` annotation that helps distinguish some of these responsibilities:
+
+* `VIEW_MENU_ONLY` indicates that the actions should appear on the menu of the xref:../ugvw/ugvw.adoc#[Wicket viewer], and as top-level actions for the REST API provided by the xref:../ugvro/ugvro.adoc#[Restful Objects viewer]
+
+* `DOMAIN` indicates that the actions are for other domain objects to invoke (either directly or indirectly through the event bus), but in any case should not be rendered at all in the UI
+
+* `VIEW_REST_ONLY` indicates that the actions should appear in the REST API provided by the xref:../ugvro/ugvro.adoc#[Restful Objects viewer], but not rendered by the xref:../ugvw/ugvw.adoc#[Wicket viewer].
+
+There are also two other natures that should be considered "deprecated":
+
+* `VIEW_CONTRIBUTIONS_ONLY` which indicates that the actions should be contributed as actions to its action parameters. +
++
+This feature is deprecated because xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_types-of-domain-objects_mixins[mixins] are equivalent in functionality with a simpler programming model.
+
+* `VIEW` combines both `VIEW_MENU_ONLY` and the deprecated `VIEW_CONTRIBUTIONS_ONLY`.
+
+If the domain service nature is not specified (or is left to its default, `VIEW`), then the service's actions will appear in the UI.
+
+While for long-term maintainability we do recommend the naming conventions described xref:../ugfun/ugfun.adoc#__ugfun_building-blocks_domain-services_organizing-services[above], you can get away with far fewer services when just prototyping a domain.
+Later on it is easy enough to refactor the code to tease apart the different responsibilities.
+
+Pulling all the above together, here are our suggestions as to how you should organize your domain services.
+

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_registering.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_registering.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_registering.adoc
new file mode 100644
index 0000000..409698a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_registering.adoc
@@ -0,0 +1,56 @@
+[[_ugfun_programming-model_domain-services_registering]]
+= Registering
+: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/
+
+
+
+The easiest way to register domain services with the framework is to use an xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`].
+This specifies the modules which contain xref:../rgant/rgant.adoc#_rgant-DomainService[`@DomainService`]-annotated classes.
+
+For example:
+
+[source,ini]
+----
+public class MyAppManifest implements AppManifest {
+    public List<Class<?>> getModules() {
+        return Arrays.asList(
+                ToDoAppDomainModule.class,
+                ToDoAppFixtureModule.class,
+                ToDoAppAppModule.class,
+                org.isisaddons.module.audit.AuditModule.class);
+    }
+    ...
+}
+----
+
+will load all services in the packages underneath the four modules listed.
+
+An alternative (older) mechanism is to registered domain services in the `isis.properties` configuration file, under `isis.services` key (a comma-separated list); for example:
+
+[source,ini]
+----
+isis.services = com.mycompany.myapp.employee.Employees\,
+                com.mycompany.myapp.claim.Claims\,
+                ...
+----
+
+This will then result in the framework instantiating a single instance of each of the services listed.
+
+If all services reside under a common package, then the `isis.services.prefix` can specify this prefix:
+
+[source,ini]
+----
+isis.services.prefix = com.mycompany.myapp
+isis.services = employee.Employees,\
+                claim.Claims,\
+                ...
+----
+
+This is quite rare, however; you will often want to use default implementations of domain services that are provided by the framework and so will not reside under this prefix.
+
+Examples of framework-provided services (as defined in the applib) include clock, auditing, publishing, exception handling, view model support, snapshots/mementos, and user/application settings management; see the xref:../rgsvc/rgsvc.adoc#[domain services] reference guide for further details.
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_repository-and-factory.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_repository-and-factory.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_repository-and-factory.adoc
new file mode 100644
index 0000000..850c05b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_repository-and-factory.adoc
@@ -0,0 +1,46 @@
+[[_ugfun_programming-model_domain-services_repository-and-factory]]
+= Repository and 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/
+
+
+
+The repository/factory uses an injected xref:../rgsvc/rgsvc.adoc#_rgsvc_api_RepositoryService[`RepositoryService`] to both instantiate new objects and to query the database for existing objects of a given entity type.
+It is not visible in UI, rather other services delegate to it.
+
+We suggest naming such classes `XxxRepository`, eg:
+
+
+[source,java]
+----
+@DomainService(
+    nature=NatureOfService.DOMAIN                               // <1>
+)
+public CustomerRepository {
+    public List<Customer> findByName(String name) {
+        return repositoryService.allMatches(                    // <2>
+                new QueryDefault<>(Customer.class,
+                            "findByName", "name", name);
+    }
+    public Customer newCustomer(...) {
+        Customer Customer =
+            repositoryService.instantiate(Customer.class);      // <3>
+        ...
+        repositoryService.persist(Customer);                    // <3>
+        return Customer;
+    }
+    public List<Customer> allCustomers() {
+        return repositoryService.allInstances(Customer.class);
+    }
+    @Inject
+    RepositoryService repositoryService;
+}
+----
+<1> interacted with only programmatically by other objects in the domain layer.
+<2> uses injected `RepositoryService` to query via JDOQL.
+<3> uses injected `RepositoryService` to first instantiate and then save into the database a new `Customer` instance.
+
+There is no need to annotate the actions; they are implicitly hidden because of the domain service's nature.
+
+

[26/58] [abbrv] isis git commit: ISIS-1521: moves subtype to ugodn

[da...@apache.org]

ISIS-1521: moves subtype to ugodn


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/31534e55
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/31534e55
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/31534e55

Branch: refs/heads/wip
Commit: 31534e5505fcc55b71ee850d7d1664707258f228
Parents: 9e1ea1b
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Sat Apr 15 11:43:57 2017 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Thu Apr 20 09:09:30 2017 +0100

----------------------------------------------------------------------
 .../guides/ugfun/_ugfun_class-structure.adoc    |  8 +++-
 .../_ugfun_class-structure_properties.adoc      | 42 -------------------
 .../_ugfun_core-concepts_building-blocks.adoc   |  6 +--
 .../guides/ugodn/_ugodn_hints-and-tips.adoc     |  3 ++
 ...ndling-mandatory-properties-in-subtypes.adoc | 44 ++++++++++++++++++++
 5 files changed, 56 insertions(+), 47 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/31534e55/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure.adoc
index 4ea4350..bd6b28e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure.adoc
@@ -5,8 +5,12 @@
 :_imagesdir: images/
 
 
-Apache Isis works by building a metamodel of the domain objects: entities, xref:../ugbtb/ugbtb.adoc#_ugbtb_view-models[view model]s and services.
-The class methods of both entities and view models represent both state -- (single-valued) properties and (multi-valued) collections -- and behaviour -- actions.  The class members of domain services is simpler: just behaviour, ie actions.
+Apache Isis works by building a metamodel of the domain objects: entities, domain services, view models and mixins.
+Dependent on the sort of domain object, the class methods represent
+both state -- (single-valued) properties and (multi-valued) collections -- and behaviour -- actions.
+
+More specifically, both entities and view models can have properties, collections and actions, while domain services have just actions.
+Mixins also define only actions, though depending on their semantics they may be rendered as derived properties or collections on the domain object to which they contribute.
 
 In the automatically generated UI a property is rendered as a field.
 This can be either of a value type (a string, number, date, boolean etc) or can be a reference to another entity.

http://git-wip-us.apache.org/repos/asf/isis/blob/31534e55/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_properties.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_properties.adoc
index 540ada1..ecff327 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_properties.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_properties.adoc
@@ -366,46 +366,4 @@ Support and maximum allowed length will vary by database vendor.
 
 
 
-[[__ugfun_class-structure_properties_handling-mandatory-properties-in-subtypes]]
-== Handling Mandatory Properties in Subtypes
-
-
-NOTE: FIXME - move to ugodn.adoc#_ugodn_hints-and-tips
-
-
-If you have a hierarchy of classes then you need to decide which inheritance strategy to use.
-
-* "table per hierarchy", or "rollup" (`InheritanceStrategy.SUPERCLASS_TABLE`) +
-+
-whereby a single table corresponds to the superclass, and also holds the properties of the subtype (or subtypes) being rolled up
-
-* "table per class" (`InheritanceStrategy.NEW_TABLE`) +
-+
-whereby there is a table for both superclass and subclass, in 1:1 correspondence
-
-* "rolldown" (`InheritanceStrategy.SUBCLASS_TABLE`) +
-+
-whereby a single table holds the properties of the subtype, and also holds the properties of its supertype
-
-In the first "rollup" case, we can have a situation where - logically speaking - the property is mandatory in the subtype - but it must be mapped as nullable in the database because it is n/a for any other subtypes that are rolled up.
-
-In this situation we must tell JDO that the column is optional, but to Apache Isis we want to enforce it being mandatory. This can be done using the `@Property(optionality=Optionality.MANDATORY)` annotation.
-
-For example:
-
-[source,java]
-----
-@javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.SUPER_TABLE)
-public class SomeSubtype extends SomeSuperType {
-    @javax.jdo.annotations.Column(allowsNull="true")
-    @Property(optionality=Optionality.MANDATORY)
-    @lombok.Getter @lombok.Setter
-    private LocalDate date;
-}
-----
-
-[TIP]
-====
-The `@Property(optionality=...)` annotation is equivalent to the older but still supported `@Optional` annotation and `@Mandatory` annotations.
-====
 

http://git-wip-us.apache.org/repos/asf/isis/blob/31534e55/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_building-blocks.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_building-blocks.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_building-blocks.adoc
index 131b470..fb106f2 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_building-blocks.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_building-blocks.adoc
@@ -109,11 +109,11 @@ If a domain service does hold state (eg the `Scratchpad` service noted above) th
 
 Every domain object in Apache Isis consists of (at most) three types of members:
 
-* properties, such as a `Customer`'s `firstName
+* properties, such as a ``Customer``'s `firstName`
 
-* collections, such as a `Customer`'s `orders` collection of ``Order``s
+* collections, such as a ``Customer``'s `orders` collection of ``Order``s
 
-* actions, such as a `Customer'`s `placeOrder(...)` method.
+* actions, such as a ``Customer'``s `placeOrder(...)` method.
 
 Some domain objects -- specifically domain services and mixins -- only have actions.
 In the case of contributing services and mixins these actions can (depending upon their semantics and signatures) be represented as derived properties or collections on the entity/view model to which they contribute/mix-in.

http://git-wip-us.apache.org/repos/asf/isis/blob/31534e55/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips.adoc
index 61806ac..de70245 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips.adoc
@@ -23,5 +23,8 @@ See also hints-n-tips chapters in the:
 
 
 include::_ugodn_hints-and-tips_overriding-jdo-annotations.adoc[leveloffset=+1]
+include::_ugodn_hints-and-tips_handling-mandatory-properties-in-subtypes.adoc[leveloffset=+1]
+
 include::_ugodn_hints-and-tips_subtype-entity-not-fully-populated.adoc[leveloffset=+1]
 include::_ugodn_hints-and-tips_java8.adoc[leveloffset=+1]
+

http://git-wip-us.apache.org/repos/asf/isis/blob/31534e55/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_handling-mandatory-properties-in-subtypes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_handling-mandatory-properties-in-subtypes.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_handling-mandatory-properties-in-subtypes.adoc
new file mode 100644
index 0000000..eff87e0
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_handling-mandatory-properties-in-subtypes.adoc
@@ -0,0 +1,44 @@
+[[_ugodn_hints-and-tips_handling-mandatory-properties-in-subtypes]]
+= Handling Mandatory Properties in Subtypes
+: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/
+
+
+
+If you have a hierarchy of classes then you need to decide which inheritance strategy to use.
+
+* "table per hierarchy", or "rollup" (`InheritanceStrategy.SUPERCLASS_TABLE`) +
++
+whereby a single table corresponds to the superclass, and also holds the properties of the subtype (or subtypes) being rolled up
+
+* "table per class" (`InheritanceStrategy.NEW_TABLE`) +
++
+whereby there is a table for both superclass and subclass, in 1:1 correspondence
+
+* "rolldown" (`InheritanceStrategy.SUBCLASS_TABLE`) +
++
+whereby a single table holds the properties of the subtype, and also holds the properties of its supertype
+
+In the first "rollup" case, we can have a situation where - logically speaking - the property is mandatory in the subtype - but it must be mapped as nullable in the database because it is n/a for any other subtypes that are rolled up.
+
+In this situation we must tell JDO that the column is optional, but to Apache Isis we want to enforce it being mandatory. This can be done using the `@Property(optionality=Optionality.MANDATORY)` annotation.
+
+For example:
+
+[source,java]
+----
+@javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.SUPER_TABLE)
+public class SomeSubtype extends SomeSuperType {
+    @javax.jdo.annotations.Column(allowsNull="true")
+    @Property(optionality=Optionality.MANDATORY)
+    @lombok.Getter @lombok.Setter
+    private LocalDate date;
+}
+----
+
+[TIP]
+====
+The `@Property(optionality=...)` annotation is equivalent to the older but still supported `@Optional` annotation and `@Mandatory` annotations.
+====
+

[29/58] [abbrv] isis git commit: ISIS-1521: fixes further xref links between guides

[da...@apache.org]

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_UserRegistrationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_UserRegistrationService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_UserRegistrationService.adoc
index 0c7fbe1..c8dcc61 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_UserRegistrationService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_UserRegistrationService.adoc
@@ -7,7 +7,7 @@
 
 The `UserRegistrationService` provides the ability for users to sign-up to access an application by providing a valid email address, and also provides the capability for users to reset their password if forgotten.
 
-For user sign-up, the xref:ugvw.adoc#[Wicket viewer] will check whether an implementation of this service (and also the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_EmailNotificationService[`EmailNotificationService`]) is available, and if so will render a sign-up page where the user enters their email address. A verification email is sent (using the aforementioned `EmailNotificationService`) which includes a link back to the running application; this allows the user then to complete their registration process (choose user name, password and so on). When the user has provided the additional details, the Wicket viewer calls _this_ service in order to create an account for them, and then logs the user on.
+For user sign-up, the xref:../ugvw/ugvw.adoc#[Wicket viewer] will check whether an implementation of this service (and also the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_EmailNotificationService[`EmailNotificationService`]) is available, and if so will render a sign-up page where the user enters their email address. A verification email is sent (using the aforementioned `EmailNotificationService`) which includes a link back to the running application; this allows the user then to complete their registration process (choose user name, password and so on). When the user has provided the additional details, the Wicket viewer calls _this_ service in order to create an account for them, and then logs the user on.
 
 For the password reset feature, the Wicket viewer will render a password reset page, and use the `EmailNotificationService` to send a "password forgotten" email.  This service provides the ability to reset a password based on the user's email address.
 
@@ -15,7 +15,7 @@ It is of course possible for domain objects to use this service; it will be inje
 
 [NOTE]
 ====
-For further details on the user registration feature (as supported by the Wicket viewer), see xref:ugvw.adoc#_ugvw_features_user-registration[here].
+For further details on the user registration feature (as supported by the Wicket viewer), see xref:../ugvw/ugvw.adoc#_ugvw_features_user-registration[here].
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_contributions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_contributions.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_contributions.adoc
index 0adf9f3..6e93ac7 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_contributions.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_contributions.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-Contributed services provide many of the same benefits as xref:ugbtb.adoc#_ugbtb_decoupling_mixins[mixins];
+Contributed services provide many of the same benefits as xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_mixins[mixins];
 indeed mixins are an evolution and refinement of the contributions concept.
 
 [WARNING]

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_db-schemas.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_db-schemas.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_db-schemas.adoc
index 4e7866b..389185c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_db-schemas.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_db-schemas.adoc
@@ -49,7 +49,7 @@ CREATE TABLE isisaudit."AuditEntry" (
 
 [TIP]
 ====
-If for some reason you don't want to use schemas (though we strongly recommend that you do), then note that you can override the `@PersistenceCapable` annotation by providing XML metadata (the `mappings.jdo` file); see the section on xref:ugodn.adoc#_ugodn_configuring[configuring DataNucleus Overriding Annotations] for more details.
+If for some reason you don't want to use schemas (though we strongly recommend that you do), then note that you can override the `@PersistenceCapable` annotation by providing XML metadata (the `mappings.jdo` file); see the section on xref:../ugodn/ugodn.adoc#_ugodn_configuring[configuring DataNucleus Overriding Annotations] for more details.
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_mixins.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_mixins.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_mixins.adoc
index 82069ba..72af4c3 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_mixins.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_mixins.adoc
@@ -229,7 +229,7 @@ method.  For example:
 DocumentHolder_documents mixin = container.mixin(DocumentHolder_documents.class, customer);
 ----
 
-The xref:ugtst.adoc#__ugtst_integ-test-support_bootstrapping_IntegrationTestAbstract[`IntegrationTestAbstract`] and
+The xref:../ugtst/ugtst.adoc#__ugtst_integ-test-support_bootstrapping_IntegrationTestAbstract[`IntegrationTestAbstract`] and
 xref:../rgcms/rgcms.adoc#_rgcms_classes_super_FixtureScript[`FixtureScript`] classes both provide a `mixin(...)` convenience
 method.
 
@@ -257,7 +257,7 @@ fundamental structure is changing is likely to remain a no-no.
 However, chances are that the structure of your domain objects (the data) will change much less rapidly than
 the behaviour of those domain objects.  Thus, it's the behaviour that you're most likely wanting to change while the
 app is still running.  If you move that behaviour out into xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins[mixins] (or
-xref:ugbtb.adoc#_ugbtb_decoupling_contributions[contributed services]), then these can be reloaded happily.
+xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_contributions[contributed services]), then these can be reloaded happily.
 (When running in prototype mode), Apache Isis will automatically recreate the portion of the metamodel for any domain
 object as it is rendered.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_pushing-changes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_pushing-changes.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_pushing-changes.adoc
index d75d8ac..abd6e52 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_pushing-changes.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_pushing-changes.adoc
@@ -7,7 +7,7 @@
 
 [NOTE]
 ====
-This technique is much less powerful than using xref:ugbtb.adoc#_ugbtb_decoupling_event-bus[the event bus] .  We present it mostly for completeness.
+This technique is much less powerful than using xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_event-bus[the event bus] .  We present it mostly for completeness.
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_externalized-configuration.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_externalized-configuration.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_externalized-configuration.adoc
index ddf5cf9..8574755 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_externalized-configuration.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_externalized-configuration.adoc
@@ -18,7 +18,7 @@ then the subsequent configuration property will be ignored.
 [TIP]
 ====
 In addition the framework will also load the `overrides.properties` file.  This is intended to support deployment
-through Docker, as discussed xref:ugbtb.adoc#_ugbtb_deployment_docker[next].
+through Docker, as discussed xref:../ugbtb/ugbtb.adoc#_ugbtb_deployment_docker[next].
 ====
 
 All of these files are read from the `WEB-INF` directory.  Having this configuration "baked into" the application is
@@ -91,7 +91,7 @@ Note that running the app using Apache Isis' `org.apache.isis.WebServer` bootstr
 [[__ugbtb_deployment_externalized-configuration_Shiro]]
 == Shiro Config
 
-If using Apache Isis' xref:ugsec.adoc#_ugsec_configuring-isis-to-use-shiro[Shiro integration] for authentication and/or authorization, note that it reads from the `shiro.ini` configuration file. By default this also resides in `WEB-INF`.
+If using Apache Isis' xref:../ugsec/ugsec.adoc#_ugsec_configuring-isis-to-use-shiro[Shiro integration] for authentication and/or authorization, note that it reads from the `shiro.ini` configuration file. By default this also resides in `WEB-INF`.
 
 Similar to Apache Isis, Shiro lets this configuration directory be altered, by specifying the `shiroConfigLocations` context parameter.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_jvm-flags.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_jvm-flags.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_jvm-flags.adoc
index 55658fe..2631e40 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_jvm-flags.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_jvm-flags.adoc
@@ -48,5 +48,5 @@ There are also a whole bunch of GC-related flags, that you might want to explore
 
 ## Configuring in Tomcat
 
-If using Tomcat, update the `CATALINA_OPTS` variable.  (This variable is also updated if xref:ugbtb.adoc#__ugbtb_deployment_externalized-configuration_Log4j[configuring logging to run externally]).
+If using Tomcat, update the `CATALINA_OPTS` variable.  (This variable is also updated if xref:../ugbtb/ugbtb.adoc#__ugbtb_deployment_externalized-configuration_Log4j[configuring logging to run externally]).
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_tomcat.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_tomcat.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_tomcat.adoc
index 9d563ac..6da4564 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_tomcat.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_tomcat.adoc
@@ -9,7 +9,7 @@ Some pointers when deploying to Tomcat (or any other servlet container).
 
 == Externalized Configuration
 
-See the guidance xref:ugbtb.adoc#_ugbtb_deployment_externalized-configuration[below].
+See the guidance xref:../ugbtb/ugbtb.adoc#_ugbtb_deployment_externalized-configuration[below].
 
 
 == JVM Args
@@ -25,4 +25,4 @@ The xref:../rgsvc/rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`] uses li
 
 == Using a JNDI Datasource
 
-See the guidance in the xref:ugodn.adoc#_ugodn_configuring_using-jndi-data-source[configuring datanucleus] section.
\ No newline at end of file
+See the guidance in the xref:../ugodn/ugodn.adoc#_ugodn_configuring_using-jndi-data-source[configuring datanucleus] section.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_headless-access.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_headless-access.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_headless-access.adoc
index 5918c12..406382a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_headless-access.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_headless-access.adoc
@@ -4,7 +4,7 @@
 :_basedir: ../../
 :_imagesdir: images/
 
-This section tackles the topic of enabling access to an Isis application directly, or at least, not through either the xref:ugvw.adoc#[Wicket] or xref:ugvro.adoc#[Restful] viewers.
+This section tackles the topic of enabling access to an Isis application directly, or at least, not through either the xref:../ugvw/ugvw.adoc#[Wicket] or xref:../ugvro/ugvro.adoc#[Restful] viewers.
 
 There are several main use-cases:
 
@@ -14,7 +14,7 @@ There are several main use-cases:
 
 * leveraging an Isis application within a batch process
 
-Note that the calling thread runs in the same process space as the Apache Isis domain object model (must be physically linked to the JAR files containing the domain classes).  For use cases where the calling thread runs in some other process space (eg migrating data from a legacy system), then the xref:ugvro.adoc#[Restful Objects viewer] is usually the way to go.
+Note that the calling thread runs in the same process space as the Apache Isis domain object model (must be physically linked to the JAR files containing the domain classes).  For use cases where the calling thread runs in some other process space (eg migrating data from a legacy system), then the xref:../ugvro/ugvro.adoc#[Restful Objects viewer] is usually the way to go.
 
 The API described in this chapter is reasonably low-level, allowing code to interact very directly with the Apache Isis metamodel and runtime.  Such callers should be considered trusted: they do not (by default) honour any business rules eg implicit in the Isis annotations or hide/disable/validate methods.  However the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`] service could be used to enforce such business rules if required.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_headless-access_BackgroundCommandExecution.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_headless-access_BackgroundCommandExecution.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_headless-access_BackgroundCommandExecution.adoc
index 2562892..137e010 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_headless-access_BackgroundCommandExecution.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_headless-access_BackgroundCommandExecution.adoc
@@ -6,7 +6,7 @@
 
 
 
-The `BackgroundCommandExecution` class (a subclass of xref:ugbtb.adoc#_ugbtb_headless-access_AbstractIsisSessionTemplate[AbstractIsisSessionTemplate]) is intended to simplify the execution of background ``Command``s persisted by way of the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] and the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[`BackgroundCommandService`].
+The `BackgroundCommandExecution` class (a subclass of xref:../ugbtb/ugbtb.adoc#_ugbtb_headless-access_AbstractIsisSessionTemplate[AbstractIsisSessionTemplate]) is intended to simplify the execution of background ``Command``s persisted by way of the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] and the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[`BackgroundCommandService`].
 
 Its signature is:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_i18n.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_i18n.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_i18n.adoc
index a81a2d8..7f925be 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_i18n.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_i18n.adoc
@@ -9,7 +9,7 @@ Apache Isis' support for internationlization (i18n) allows every element of the
 
 It also supports translations of messages raised imperatively, by which we mean as the result of a call to `title()` to obtain an object's title, or messages resulting from any business rule violations (eg xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_disable[`disable...()`] or xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_validate[`validate...()`], and so on.
 
-The xref:ugvw.adoc#[Wicket viewer] (that is, its labels and messages) is also internationalized using the same mechanism.  If no translations are available, then the Wicket viewer falls back to using Wicket resource bundles.
+The xref:../ugvw/ugvw.adoc#[Wicket viewer] (that is, its labels and messages) is also internationalized using the same mechanism.  If no translations are available, then the Wicket viewer falls back to using Wicket resource bundles.
 
 Isis does not translate the values of your domain objects, though.  So, if you have a domain concept such as `Country` whose name is intended to be localized according to the current user, you will need to model this yourself.
 
@@ -223,7 +223,7 @@ public interface TranslatableException {
 [[__ugbtb_i18n_wicket-viewer]]
 == Wicket Viewer
 
-The xref:ugvw.adoc#[Wicket viewer] (its labels and messages) is also internationalized using
+The xref:../ugvw/ugvw.adoc#[Wicket viewer] (its labels and messages) is also internationalized using
 the `TranslationService`.  This is done through an Isis-specific implementation of the Wicket framework's `org.apache.wicket.Localizer` class, namely `LocalizerForIsis`.
 
 The Wicket `Localizer` defines the following API:
@@ -322,7 +322,7 @@ msgstr "You can only select 1 item"
 === Login/self-sign-up
 
 In addition, there are a reasonably large number of messages that are used for both login and the
- xref:ugvw.adoc#_ugvw_features_user-registration[user registration] (self sign-up) and password reset features.
+ xref:../ugvw/ugvw.adoc#_ugvw_features_user-registration[user registration] (self sign-up) and password reset features.
 
 These are:
 
@@ -479,7 +479,7 @@ msgstr "Username"
 
 So much for the API; but as noted, it is also necessary to ensure that the required translations are recorded (by the `TranslationService`) into the `.pot` file.
 
-For this, we recommend that you ensure that all such methods are tested through an xref:ugtst.adoc#_ugtst_integ-test-support[integration test] (not unit test).
+For this, we recommend that you ensure that all such methods are tested through an xref:../ugtst/ugtst.adoc#_ugtst_integ-test-support[integration test] (not unit test).
 
 For example, here's the corresponding integration test for the "Exclamation mark" example from the simpleapp (above):
 
@@ -540,7 +540,7 @@ msgstr "<i>Quantit�</i>"
 ----
 
 For this to work, the `namedEscaped()` attribute must be specified using either the
-xref:ugvw.adoc#_ugvw_layout_file-based[layout file], or using an annotation such as
+xref:../ugvw/ugvw.adoc#_ugvw_layout_file-based[layout file], or using an annotation such as
 xref:../rgant/rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`] or xref:../rgant/rgant.adoc#_rgant-ParameterLayout[`@ParameterLayout`].
 
 For example:
@@ -607,7 +607,7 @@ The basename for translation files is always `translations`; this cannot be alte
 
 === Externalized translation files
 
-Normally Apache Isis configuration files are read from the `WEB-INF` file. However, Apache Isis can be configured to read config files from an xref:ugbtb.adoc#_ugbtb_deployment_externalized-configuration[external directory]; this is also supported for translations.
+Normally Apache Isis configuration files are read from the `WEB-INF` file. However, Apache Isis can be configured to read config files from an xref:../ugbtb/ugbtb.adoc#_ugbtb_deployment_externalized-configuration[external directory]; this is also supported for translations.
 
 Thus, if in `web.xml` the external configuration directory has been set:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_transactions-and-errors.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_transactions-and-errors.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_transactions-and-errors.adoc
index 85ed7f6..54d068c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_transactions-and-errors.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_transactions-and-errors.adoc
@@ -41,8 +41,8 @@ You get the idea.
 == Raise message/errors to users
 
 The framework provides the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_MessageService[`MessageService`] as a means to return an out-of-band
-message to the end-user.  In the xref:ugvw.adoc#[Wicket viewer] these are shown as "toast" pop-ups; the
-xref:ugvro.adoc#[Restful Objects viewer] returns an HTTP header.
+message to the end-user.  In the xref:../ugvw/ugvw.adoc#[Wicket viewer] these are shown as "toast" pop-ups; the
+xref:../ugvro/ugvro.adoc#[Restful Objects viewer] returns an HTTP header.
 
 The `UserService` provides three APIs, for different:
 
@@ -58,8 +58,8 @@ None of these messages/errors has any influence on the transaction; any changes
 == Aborting transactions
 
 If you want to abort Apache Isis' transaction, this can be done by throwing an exception.  The exception message
-is displayed to the user on the error page (if xref:ugvw.adoc#[Wicket viewer]) or a 500 status error code (if the
-xref:ugvro.adoc#[Restful Objects] viewer).
+is displayed to the user on the error page (if xref:../ugvw/ugvw.adoc#[Wicket viewer]) or a 500 status error code (if the
+xref:../ugvro/ugvro.adoc#[Restful Objects] viewer).
 
 If the exception thrown is because of an unexpected error (eg a `NullPointerException` in the domain app itself), then
 the error page will include a stack trace.  If however you want to indicate that the exception is in some sense

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_programming-model_finetuning.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_programming-model_finetuning.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_programming-model_finetuning.adoc
index ecaaf3d..26eb886 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_programming-model_finetuning.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_programming-model_finetuning.adoc
@@ -58,7 +58,7 @@ To include/exclude more than one `FacetFactory`, specify as a comma-separated li
 
 [TIP]
 ====
-This http://isis.markmail.org/thread/472c3mrvcgnripst[thread] from the users mailing list (in Apr 2014) shows a typical customization (to enable per-instance security) (though note that xref:ugbtb.adoc#_ugbtb_other-techniques_multi-tenancy[Multi-Tenancy] is now a better solution to that particular use-case.
+This http://isis.markmail.org/thread/472c3mrvcgnripst[thread] from the users mailing list (in Apr 2014) shows a typical customization (to enable per-instance security) (though note that xref:../ugbtb/ugbtb.adoc#_ugbtb_other-techniques_multi-tenancy[Multi-Tenancy] is now a better solution to that particular use-case.
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_programming-model_layout-metadata-reader.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_programming-model_layout-metadata-reader.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_programming-model_layout-metadata-reader.adoc
index 432d46d..e468ee3 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_programming-model_layout-metadata-reader.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_programming-model_layout-metadata-reader.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-The metadata for domain objects is obtained both xref:ugvw.adoc#_ugvw_layout_annotation-based[annotations] and xref:ugvw.adoc#_ugvw_layout_file-based[files].
+The metadata for domain objects is obtained both xref:../ugvw/ugvw.adoc#_ugvw_layout_annotation-based[annotations] and xref:../ugvw/ugvw.adoc#_ugvw_layout_file-based[files].
 There is also deprecated support for reading layouts from `.layout.json` files.
 This service provides an SPI (and default implementation) for reading layouts defined in this fashion.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_jaxb.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_jaxb.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_jaxb.adoc
index 00ae0b6..258f9e2 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_jaxb.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_jaxb.adoc
@@ -6,11 +6,11 @@
 
 
 
-As noted in the xref:ugbtb.adoc#_ugbtb_view-models_use-cases[introduction], view models can also be defined using JAXB annotations.
+As noted in the xref:../ugbtb/ugbtb.adoc#_ugbtb_view-models_use-cases[introduction], view models can also be defined using JAXB annotations.
 The serialized form of these view models is therefore XML, which also enables these view models
 to act as DTOs.
 
-In case it's not obvious, these DTOs are still usable as "regular" view models; they will render in the xref:ugvw.adoc#[Wicket viewer] just like any other.
+In case it's not obvious, these DTOs are still usable as "regular" view models; they will render in the xref:../ugvw/ugvw.adoc#[Wicket viewer] just like any other.
 In fact, these JAXB-annotated view models are in many regards the most powerful of all the various ways of writing view models:
 
 * their entire state (collections as well as properties) is automatically managed from interaction to interaction. +
@@ -59,16 +59,16 @@ public class ToDoItemV1_1 implements Dto {                          // <5>
     protected List<ToDoItem> similarItems = Lists.newArrayList();
 }
 ----
-<1> package name encodes major version; see discussion on xref:ugbtb.adoc#__ugbtb_view-models_jaxb_versioning[versioning]
+<1> package name encodes major version; see discussion on xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_versioning[versioning]
 <2> identifies this class as a view model and defines the root element for JAXB serialization
 <3> all properties in the class must be listed; (they can be ignored using `@XmlTransient`)
 <4> demonstrating use of UI events for a subscriber to provide the DTO's title; see xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_titleUiEvent[`@DomainObjectLayout#titleUiEvent()`].
-<5> class name encodes (major and) minor version; see discussion on xref:ugbtb.adoc#__ugbtb_view-models_jaxb_versioning[versioning]
-<6> again, see discussion on xref:ugbtb.adoc#__ugbtb_view-models_jaxb_versioning[versioning]
-<7> again, see discussion on xref:ugbtb.adoc#__ugbtb_view-models_jaxb_versioning[versioning]
+<5> class name encodes (major and) minor version; see discussion on xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_versioning[versioning]
+<6> again, see discussion on xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_versioning[versioning]
+<7> again, see discussion on xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_versioning[versioning]
 <8> simple scalar properties
-<9> reference to a persistent entity; discussed xref:ugbtb.adoc#__ugbtb_view-models_jaxb_referencing-domain-entities[below]
-<10> reference to a collection of persistent entities; again discussed xref:ugbtb.adoc#__ugbtb_view-models_jaxb_referencing-domain-entities[below]
+<9> reference to a persistent entity; discussed xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_referencing-domain-entities[below]
+<10> reference to a collection of persistent entities; again discussed xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_referencing-domain-entities[below]
 
 
 
@@ -186,7 +186,7 @@ Although there is no requirement for the namespace URI to correspond to a physic
 This usually means including a company domain name within the string.
 
 As noted above, this package will contain multiple DTO classes all with the same namespace; these represent a set of minor versions of the DTO, each subsequent one intended to be backwardly compatible with the previous.
-Since these DTO classes will all be in the same package (as per the xref:ugbtb.adoc#__ugbtb_view-models_jaxb_using-packages-to-version[advice above]), the class should therefore include the minor version name:
+Since these DTO classes will all be in the same package (as per the xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_using-packages-to-version[advice above]), the class should therefore include the minor version name:
 
 [source,java]
 ----
@@ -246,7 +246,7 @@ We also _don't_ recommend using inheritance (ie `ToDoItemV1_2` should not inheri
 [[__ugbtb_view-models_jaxb_generating-xsds-and-dtos]]
 == Generating XSDs and DTOs
 
-In the section xref:ugbtb.adoc#__ugbtb_view-models_jaxb_referencing-domain-entities[above] it was explained how a view model DTO can transparent reference any "backing" entities; these references are converted to internal object identifiers.
+In the section xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_referencing-domain-entities[above] it was explained how a view model DTO can transparent reference any "backing" entities; these references are converted to internal object identifiers.
 
 However, if the consumer of the XML is another Java process (eg running within an Apache Camel route), then you might be tempted/expect to be able to use the same DTO within that Java process.
 After a little thought though you'll realize that (duh!) of course you cannot; the consumer runs in a different process space, and will not have references to those containing entities.

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_use-cases.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_use-cases.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_use-cases.adoc
index 66c547e..a58f57c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_use-cases.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_use-cases.adoc
@@ -102,20 +102,20 @@ DTOs (data transfer objects) are simple classes that (according to link:https://
 
 If those two processes are parts of the same overall application (the same team builds and deploys both server and
 client) then there's generally no need to define a DTO; just access the entities using Apache Isis'
-xref:ugvro.adoc#[RestfulObjects viewer].
+xref:../ugvro/ugvro.adoc#[RestfulObjects viewer].
 
 On the other hand, if the client consuming the DTO is a different application -- by which we mean developed/deployed by
 a different (possible third-party) team -- then the DTOs act as a formal contract between the provider and the consumer.
-In such cases, exposing domain entities over xref:ugvro.adoc#[RestfulObjects] would be
+In such cases, exposing domain entities over xref:../ugvro/ugvro.adoc#[RestfulObjects] would be
 "A Bad Thing"(TM) because the consumer would in effect have access to implementation details that could then not be
 easily changed by the producer.
 
 To support this use case, a view model can be defined such that it can act as a DTO.  This is done by annotating the
 class using JAXB annotations; this allows the consumer to obtain the DTO in XML format along with a corresponding
 XSD schema describing the structure of that XML.  A discussion of how that might be done using an ESB such as
-link:http://camel.apache.org[Apache Camel(TM)] follows xref:ugbtb.adoc#__ugbtb_view-models_use-cases_dtos_consumers[below].
+link:http://camel.apache.org[Apache Camel(TM)] follows xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_use-cases_dtos_consumers[below].
 
-In case it's not obvious, these DTOs are still usable as "regular" view models; they will render in the xref:ugvw.adoc#[Wicket viewer] just like any other.  In fact (as the xref:ugbtb.adoc#_ugbtb_view-models_programming-model[programming model] section below makes clear), these JAXB-annotated view models are in many regards the most powerful of all the alternative ways of writing view models.
+In case it's not obvious, these DTOs are still usable as "regular" view models; they will render in the xref:../ugvw/ugvw.adoc#[Wicket viewer] just like any other.  In fact (as the xref:../ugbtb/ugbtb.adoc#_ugbtb_view-models_programming-model[programming model] section below makes clear), these JAXB-annotated view models are in many regards the most powerful of all the alternative ways of writing view models.
 
 
 It's also worth noting that it is also possible to download the XML (or XSD) straight from the UI, useful during development.
@@ -127,7 +127,7 @@ framework has xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins_Dto[mixins] that co
 === DTO Consumers
 
 The actual consumers of DTOs will generally obtain the XML of the view models either by requesting the XML directly,
-eg using the xref:ugvro.adoc#[RestfulObjects viewer], or may have the XML sent to them asynchronously using an ESB
+eg using the xref:../ugvro/ugvro.adoc#[RestfulObjects viewer], or may have the XML sent to them asynchronously using an ESB
 such as Apache Camel.
 
 In the former case, the consumer requests the DTO by calling the REST API with the appropriate HTTP `Accept` header.
@@ -153,7 +153,7 @@ The (non-ASF) http://github.com/isisaddons/isis-module-publishmq[Isis addons' pu
 but which simply publishes instances of xref:../rgcms/rgcms.adoc#_rgcms_schema-aim[`ActionInvocationMemento`] to an ActiveMQ
 queue.  Camel (or similar) can then be hooked up to consume these events from this queue, and use a processor to
 parse the action memento to determine what has changed on the source system.  Thereafter, a subsequent Camel processor
-can then call back to the source - via the xref:ugvro.adoc[Restful Objects viewer] - to enrich the message with
+can then call back to the source - via the xref:../ugvro/ugvro.adoc[Restful Objects viewer] - to enrich the message with
 additional details using a DTO.
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_web-xml.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_web-xml.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_web-xml.adoc
index 8f03333..d8ab5c2 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_web-xml.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_web-xml.adoc
@@ -6,9 +6,9 @@
 
 
 
-Apache Isis provides two different viewers, the xref:ugvw.adoc#[Wicket viewer] and the xref:ugvro.adoc#[RestfulObjects viewer].  You can deploy both of these concurrently, or deploy just the Wicket viewer, or deploy just the Restful Objects viewer.  The configuration in `web.xml` varies accordingly, both in terms of the servlet context listeners, filters and servlets.
+Apache Isis provides two different viewers, the xref:../ugvw/ugvw.adoc#[Wicket viewer] and the xref:../ugvro/ugvro.adoc#[RestfulObjects viewer].  You can deploy both of these concurrently, or deploy just the Wicket viewer, or deploy just the Restful Objects viewer.  The configuration in `web.xml` varies accordingly, both in terms of the servlet context listeners, filters and servlets.
 
-If you are using Apache Isis' integration with Apache Shiro (for security) then this also needs configuring in `web.xml`.  See the xref:ugsec.adoc#_ugsec_configuring-isis-to-use-shiro[security chapter] for full details on this topic.
+If you are using Apache Isis' integration with Apache Shiro (for security) then this also needs configuring in `web.xml`.  See the xref:../ugsec/ugsec.adoc#_ugsec_configuring-isis-to-use-shiro[security chapter] for full details on this topic.
 
 The servlets and filters are mapped to three main pipelines:
 
@@ -449,7 +449,7 @@ This filter should be mapped to the `servlet-name` for the RestEasy `HttpServlet
 === `IsisTransactionFilterForRestfulObjects`
 
 The `IsisTransactionFilterForRestfulObjects` filter simply ensures that a transaction is in progress for all
-calls routed to the xref:ugvro.adoc#[RestfulObjects viewer].
+calls routed to the xref:../ugvro/ugvro.adoc#[RestfulObjects viewer].
 
 Its definition is:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugbtb/ugbtb.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/ugbtb.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/ugbtb.adoc
index 3e7b19d..70276b2 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/ugbtb.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/ugbtb.adoc
@@ -9,10 +9,10 @@
 [[_ugbtb]]
 == Beyond the Basics
 
-This guide provides xref:ugbtb.adoc#_ugbtb_other-techniques[more advanced] guidance on writing maintainable larger
+This guide provides xref:../ugbtb/ugbtb.adoc#_ugbtb_other-techniques[more advanced] guidance on writing maintainable larger
 applications.
 
-Later chapters discuss how to xref:ugbtb.adoc#_ugbtb_deployment[deploy] your app, and discuss other ways in which you can xref:ugbtb.adoc#[extend] or adapt the framework itself to your particular needs.
+Later chapters discuss how to xref:../ugbtb/ugbtb.adoc#_ugbtb_deployment[deploy] your app, and discuss other ways in which you can xref:../ugbtb/ugbtb.adoc#[extend] or adapt the framework itself to your particular needs.
 
 === Other Guides
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_cqrs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_cqrs.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_cqrs.adoc
index 37eb157..9f7b296 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_cqrs.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_cqrs.adoc
@@ -32,7 +32,7 @@ In these cases Apache Isis can often provide a reasonable alternative, namely to
 In such cases there is still only a single physical datastore, and so transactional integrity is retained.
 
 Or, the CQRS architecture can be more fully implemented with Apache Isis by introducing a separate read model, synchronized using the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_PublishingService[`PublishingService`], or using xref:../rgcms/rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscribers]  on the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`].
-One can then use xref:ugbtb.adoc#_ugbtb_view-models[view models] to surface the data in the external read datastore.
+One can then use xref:../ugbtb/ugbtb.adoc#_ugbtb_view-models[view models] to surface the data in the external read datastore.
 
 With respect to commands, Apache Isis does of course support the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] which allows each business action to be reified into a `Command`.
 However, names are misleading here: Apache Isis' commands are relatively passive, merely recording the intent of the user to invoke some operation.
@@ -43,7 +43,7 @@ With Apache Isis, though, the end-user merely invokes the `placeOrder(...)` acti
 In CQRS the commands correspond to the business logic that mutates the system.
 Whether this logic is part of the command class (`PlaceOrderCommand`) or whether that command delegates to methods on the domain object is an implementation detail; but it certainly is common for the business logic to be wholly within the command object and for the domain object to be merely a data holder of the data within the command/write datastore.
 
-In Apache Isis this same separation of business logic from the underlying data can be accomplished most straightforwardly using xref:ugbtb.adoc#_ugbtb_decoupling_mixins[mixins] or xref:../ugfun/ugfun.adoc#_ugfun_how-tos_contributed-members[contributions].
-In the UI (surfaced by the xref:ugvw.adoc#[Wicket viewer]) or in the REST API (surfaced by the xref:ugvro.adoc#[RestfulObjects viewer]) the behaviour appears to reside on the domain object; however the behaviour actually resides on separate classes and is mixed in (like a trait) only at runtime.
+In Apache Isis this same separation of business logic from the underlying data can be accomplished most straightforwardly using xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_mixins[mixins] or xref:../ugfun/ugfun.adoc#_ugfun_how-tos_contributed-members[contributions].
+In the UI (surfaced by the xref:../ugvw/ugvw.adoc#[Wicket viewer]) or in the REST API (surfaced by the xref:../ugvro/ugvro.adoc#[RestfulObjects viewer]) the behaviour appears to reside on the domain object; however the behaviour actually resides on separate classes and is mixed in (like a trait) only at runtime.
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_metawidget.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_metawidget.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_metawidget.adoc
index 22c1cf4..5eaa883 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_metawidget.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_metawidget.adoc
@@ -11,7 +11,7 @@ And like Apache Isis, MetaWidget builds its own metamodel of the domain objects
 However, there is a difference in philosophy in that MW is not a full-stack framework and does not (in their words) try to "own the UI".
 Rather they support a huge variety of UI technologies and allow the domain object to be rendered in any of them.
 
-In contrast, Apache Isis is full-stack and does generate a complete UI; we then allow you to customize or extend this UI (as per the various link:http://www.isisaddons.org[Isis Addons] (non-ASF), and we also provide a full REST API through the xref:ugvro.adoc#[Restful Objects viewer]
+In contrast, Apache Isis is full-stack and does generate a complete UI; we then allow you to customize or extend this UI (as per the various link:http://www.isisaddons.org[Isis Addons] (non-ASF), and we also provide a full REST API through the xref:../ugvro/ugvro.adoc#[Restful Objects viewer]
 
 Also, it's worth noting that MetaWidget does have an elegant pipeline architecture, with APIs to allow even its metamodel to be replaced.
 It would be feasible and probably quite straightforward to use Apache Isis' own metamodel as an implementation of the MetaWidget API.

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_mvc-server-side-frameworks.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_mvc-server-side-frameworks.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_mvc-server-side-frameworks.adoc
index 81933df..b806289 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_mvc-server-side-frameworks.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_mvc-server-side-frameworks.adoc
@@ -14,7 +14,7 @@ The views provided out of the box by these frameworks tend to be simple  _CRUD_-
 More sophisticated behavior is accomplished by customizing the generated controllers.
 
 The most obvious difference when developing an Apache Isis application is its deliberate lack of an explicit controller layer; non- _CRUD_ behavior is automatically made available in its generic object-oriented  _UI_s.
-More sophisticated UIs can be built either by xref:ugvw.adoc#_ugvw_extending[extending Apache Isis' Wicket viewer] or by writing a bespoke UI leveraging the REST (hypermedia) API automatically exposed by xref:ugvro.adoc#[Isis' Restful Objects viewer].
+More sophisticated UIs can be built either by xref:../ugvw/ugvw.adoc#_ugvw_extending[extending Apache Isis' Wicket viewer] or by writing a bespoke UI leveraging the REST (hypermedia) API automatically exposed by xref:../ugvro/ugvro.adoc#[Isis' Restful Objects viewer].
 Other frameworks can also be used to implement REST APIs, of course, but generally they require a significant amount of development to get anywhere near the level of sophistication provided automatically by Apache Isis' REST API.
 
 Although these frameworks all provide their own ecosystems of extensions, Apache Isis' equivalent link:http://www.isisaddons.org[Isis Addons] (non-ASF) tend to work at a higher-level of abstraction.
@@ -25,5 +25,5 @@ Again, these addons can be plugged into any Isis app.
 In terms of testing support, each of these other frameworks provide mechanisms to allow the webapp to be tested from within a JUnit test harness.
 Apache Isis' support is similar.
 Where Apache Isis differs though is that it enables end-to-end testing without the need for slow and fragile Selenium tests.
-Instead, Apache Isis provides a "xref:ugtst.adoc#_ugtst_integ-test-support_wrapper-factory[WrapperFactory]" domain service that allows the generic UI provided to in essence be simulated.
+Instead, Apache Isis provides a "xref:../ugtst/ugtst.adoc#_ugtst_integ-test-support_wrapper-factory[WrapperFactory]" domain service that allows the generic UI provided to in essence be simulated.
 On a more pragmatic level, the http://github.com/isisaddons/isis-module-fakedata[Isis addons' fakedata] module does "what it says on the tin", allowing both unit- and integration-tests to focus on the salient data and fake out the rest.

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_building-blocks.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_building-blocks.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_building-blocks.adoc
index 950f175..131b470 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_building-blocks.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_building-blocks.adoc
@@ -13,7 +13,7 @@ At its core, Apache Isis is a metamodel that is built at runtime from the domain
 
 The contents of this metamodel is inferred from the Java classes discovered on the classpath: the entities and supporting services, as well the members of those classes.
 The detail of the metamodel is generally explicit, usually represented by Java annotations such as `@Title` or `@Action`.
-Notably the metamodel is xref:ugbtb.adoc#_ugbtb_programming-model[extensible]; it is possible to teach Apache Isis new programming conventions/rules (and conversely to remove those that are built in).
+Notably the metamodel is xref:../ugbtb/ugbtb.adoc#_ugbtb_programming-model[extensible]; it is possible to teach Apache Isis new programming conventions/rules (and conversely to remove those that are built in).
 
 Most of the annotations recognized by the framework are defined by the Apache Isis framework itself.
 For example the `@Title` annotation -- which identifies how the framework should derive a human-readable label for each rendered domain object -- is part of the `org.apache.isis.applib.annotations` package.
@@ -24,7 +24,7 @@ This is an ORM that implements the JDO and JPA APIs, and which can map domain ob
 Apache Isis recognizes a number of the JDO annotations such as `@javax.jdo.annotations.Column(allowsNull=...)`.
 
 In addition, the framework builds up the metamodel for each domain object using
-xref:ugvw.adoc#_ugvw_layout[layout hints], such as `Customer.layout.xml`.
+xref:../ugvw/ugvw.adoc#_ugvw_layout[layout hints], such as `Customer.layout.xml`.
 These provide metadata such as grouping elements of the UI together, using multi-column layouts, and so on.
 The layout file can be modified while the application is still running, and are picked up automatically; a useful way to speed up feedback.
 
@@ -44,7 +44,7 @@ From the end-user's perspective the UI displays a single domain object per page;
 
 The next type of domain object to discuss is *domain services*.
 These are (usually) singleton stateless services that provide additional functionality.
-The behaviour of these services is rendered in various ways, though the most obvious is as the menu actions on the top-level menu bars in the xref:ugvw.adoc#[Wicket viewer]'s UI.
+The behaviour of these services is rendered in various ways, though the most obvious is as the menu actions on the top-level menu bars in the xref:../ugvw/ugvw.adoc#[Wicket viewer]'s UI.
 
 Domain objects can also delegate to domain services; domain services are automatically injected into every other domain object; this includes domain entities as well as other services.
 This injection of domain services into entities is significant: it allows business logic to be implemented in the domain entities, rather than have it "leach away" into
@@ -54,7 +54,7 @@ Said another way: it is the means by which Apache Isis helps you avoid the anaem
 As well as domain entities -- mapped to a datastore -- Apache Isis also supports *view models*.
 End users interact with view models in the same way as a domain entity, indeed they are unlikely to distinguish one from the other.
 However view models are _not_ mapped to the underlying database, rather they represent some aggregation of state from one or more underlying entities.
-Their state is serialized and recreated from their internal identifier; this identifier is visible as the object's URL in the xref:ugvw.adoc#[Wicket viewer] or xref:ugvro.adoc#[RestfulObjects viewer].
+Their state is serialized and recreated from their internal identifier; this identifier is visible as the object's URL in the xref:../ugvw/ugvw.adoc#[Wicket viewer] or xref:../ugvro/ugvro.adoc#[RestfulObjects viewer].
 
 There's no need though for the view model to aggregate the state of regular domain entities.
 A view model could also be used as a proxy for some externally managed entity, accessed over a web service or REST API; it could even be a representation of state held in-memory (such as user preferences, for example).
@@ -97,7 +97,7 @@ functionality is simply for other domain objects to invoke programmatically).
 +
 It is also possible to specify a nature of simply `VIEW`, this combining `VIEW_MENU_ONLY` and `VIEW_CONTRIBUTIONS_ONLY`.
 This is in fact the default, useful for initial prototyping.
-A final nature is `VIEW_REST_ONLY` which is for domain services whose functionality is surfaced only by the xref:ugvro.adoc#[RestfulObjects viewer].
+A final nature is `VIEW_REST_ONLY` which is for domain services whose functionality is surfaced only by the xref:../ugvro/ugvro.adoc#[RestfulObjects viewer].
 
 Worth emphasising is that domain entities and view models hold state, whereas domain services are generally stateless.
 If a domain service does hold state (eg the `Scratchpad` service noted above) then it should be `@RequestScoped` so that this state is short-lived and usable only within a single request.
@@ -204,7 +204,7 @@ View models generally tend to be associated with supporting a particular use cas
 We introduce view models here because they do get mentioned quite often within the users and reference guide.
 However, we do consider them a more advanced topic; we generally recommend that you build your applications from the domain layer up, rather than from the view model down.
 
-For further discussion on view models, see xref:ugbtb.adoc#_ugbtb_view-models[this topic].
+For further discussion on view models, see xref:../ugbtb/ugbtb.adoc#_ugbtb_view-models[this topic].
 
 
 
@@ -244,7 +244,7 @@ Indeed, it is quite common to have a domain service that acts as both a factory
 NOTE: FIXME
 
 
-For more information, see xref:ugbtb.adoc#_ugbtb_decoupling_contributions[this topic on contribution]s, and xref:ugbtb.adoc#_ugbtb_decoupling_mixins[this topic on mixin]s.
+For more information, see xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_contributions[this topic on contribution]s, and xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_mixins[this topic on mixin]s.
 
 
 
@@ -293,8 +293,8 @@ objects
 * similarly within implementations of xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`]
 to persist published action invocations
 
-* and of course both the xref:ugvro.adoc#[RestfulObjects viewer] and
-xref:ugvw.adoc#[Wicket viewer]
+* and of course both the xref:../ugvro/ugvro.adoc#[RestfulObjects viewer] and
+xref:../ugvw/ugvw.adoc#[Wicket viewer]
 use the oid tuple to look up, render and allow the user to interact with domain objects.
 
 Although the exact content of an OID should be considered opaque by domain objects, it is possible for domain objects to obtain OIDs.

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_other-deployment-options.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_other-deployment-options.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_other-deployment-options.adoc
index b38c55c..049b883 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_other-deployment-options.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_other-deployment-options.adoc
@@ -51,7 +51,7 @@ If you go this route, your deployment platform will of course need to provide si
 
 REST (Representation State Transfer) is an architectural style for building highly scalable distributed systems, using the same principles as the World Wide Web. Many commercial web APIs (twitter, facebook, Amazon) are implemented as either pure REST APIs or some approximation therein.
 
-The http://restfulobjects.org[Restful Objects specification] defines a means by a domain object model can be exposed as RESTful resources using JSON representations over HTTP. Apache Isis' xref:ugvro.adoc#[RestfulObjects viewer] is an implementation of that spec, making any Apache Isis domain object automatically available via REST.
+The http://restfulobjects.org[Restful Objects specification] defines a means by a domain object model can be exposed as RESTful resources using JSON representations over HTTP. Apache Isis' xref:../ugvro/ugvro.adoc#[RestfulObjects viewer] is an implementation of that spec, making any Apache Isis domain object automatically available via REST.
 
 There are a number of use cases for deploying Isis as a REST API, including:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_aop.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_aop.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_aop.adoc
index 7a640ba..b1f20e0 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_aop.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_aop.adoc
@@ -48,7 +48,7 @@ Again, this is all transparent to the user.
 
 Apache Isis also has an internal event bus (you can switch between an underlying implementation of Gauva or Axon).
 A domain event is fired whenever an object is interacted with, and this allows any subscribers to influence the operation (or even veto it).
-This is a key mechanism in ensuring that Isis applications are maintainable, and we discuss it in depth in the section on  xref:ugbtb.adoc#_ugbtb_decoupling[Decoupling].
+This is a key mechanism in ensuring that Isis applications are maintainable, and we discuss it in depth in the section on  xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling[Decoupling].
 But fundamentally its relying on this AOP concept of interceptors.
 
 Finally, Isis also a feature that is akin to AOP mix-ins.
@@ -62,4 +62,4 @@ Apache Isis' support for contributions (not only contributed actions, but also c
 And again, to loop back to the topic of this section, it's an AOP concept that being implemented by the framework.
 
 The nice thing about aspect orientation is that for the most part you can ignore these cross-cutting concerns and - at least initially at least - just focus on implementing your domain object.
-Later when your app starts to grow and you start to break it out into smaller modules, you can leverage Apache Isis' AOP support for (xref:ugbtb.adoc#_ugbtb_decoupling_mixins[mixins]), (xref:ugbtb.adoc#_ugbtb_decoupling_contributions[contributions]) and interceptors (the xref:ugbtb.adoc#_ugbtb_decoupling_event-bus[event bus]) to ensure that your codebase remains maintainable.
\ No newline at end of file
+Later when your app starts to grow and you start to break it out into smaller modules, you can leverage Apache Isis' AOP support for (xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_mixins[mixins]), (xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_contributions[contributions]) and interceptors (the xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_event-bus[event bus]) to ensure that your codebase remains maintainable.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles.adoc
index 6f5c5d0..12e3768 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles.adoc
@@ -7,8 +7,8 @@
 
 
 Apache Isis is primarily aimed at custom-built "enterprise" applications.
-The UI provided by the xref:ugvw.adoc#[Wicket viewer] is intended to be usable by domain experts, typically end-users within the organization.pdf
-The REST API exposed by the xref:ugvro.adoc#[RestfulObjects viewer] allows custom apps to be developed -- eg using Angular or similar -- for use by those requiring more guidance; typically end-users outside of the organization.
+The UI provided by the xref:../ugvw/ugvw.adoc#[Wicket viewer] is intended to be usable by domain experts, typically end-users within the organization.pdf
+The REST API exposed by the xref:../ugvro/ugvro.adoc#[RestfulObjects viewer] allows custom apps to be developed -- eg using Angular or similar -- for use by those requiring more guidance; typically end-users outside of the organization.
 This section describes some of the core principles and values that the framework aims to honour and support.
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_for-the-long-term.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_for-the-long-term.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_for-the-long-term.adoc
index 6fa5091..2161ed0 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_for-the-long-term.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_for-the-long-term.adoc
@@ -23,7 +23,7 @@ The diagram below illustrates this:
 .decoupled applications
 image::{_imagesdir}core-concepts/philosophy/decoupled-applications.png[width="800px",link="{_imagesdir}core-concepts/philosophy/decoupled-applications.png"]
 
-Here, the presentation layer (xref:ugvw.adoc#[Wicket UI] or xref:ugvro.adoc#[REST API]) is handled by the framework, while the developer focusses on just the domain layer.
+Here, the presentation layer (xref:../ugvw/ugvw.adoc#[Wicket UI] or xref:../ugvro/ugvro.adoc#[REST API]) is handled by the framework, while the developer focusses on just the domain layer.
 The framework encourages splitting this functionality into modules; each such module has its counterpart (typically tables within a given RDBMS database schema) within the persistence layer.
 
 This architecture means that it's impossible for business logic to leach out into the adjacent presentation layer because the developer doesn't (can't) write any code for presentation layer.

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_simpleapp-archetype.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_simpleapp-archetype.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_simpleapp-archetype.adoc
index f0a36cb..9ee535d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_simpleapp-archetype.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started_simpleapp-archetype.adoc
@@ -89,7 +89,7 @@ where `myapp` is the `artifactId` entered above.
 
 == Running the App
 
-The `simpleapp` archetype generates a single WAR file, configured to run both the xref:ugvw.adoc#[Wicket viewer] and the xref:ugvro.adoc#[Restful Objects viewer].  The archetype also configures the DataNucleus/JDO Objectstore to use an in-memory HSQLDB connection.
+The `simpleapp` archetype generates a single WAR file, configured to run both the xref:../ugvw/ugvw.adoc#[Wicket viewer] and the xref:../ugvro/ugvro.adoc#[Restful Objects viewer].  The archetype also configures the DataNucleus/JDO Objectstore to use an in-memory HSQLDB connection.
 
 Once you've built the app, you can run the WAR in a variety of ways.
 
@@ -130,7 +130,7 @@ image::{_imagesdir}getting-started/simpleapp-webapp.png[width="600px",link="{_im
 
 == Running with Fixtures
 
-It is also possible to start the application with a pre-defined set of data; useful for demos or manual exploratory testing.  This is done by specifying a xref:ugtst.adoc#_ugtst_fixture-scripts[fixture script] on the command line.
+It is also possible to start the application with a pre-defined set of data; useful for demos or manual exploratory testing.  This is done by specifying a xref:../ugtst/ugtst.adoc#_ugtst_fixture-scripts[fixture script] on the command line.
 
 If you are running the app from an IDE, then you can specify the fixture script using the `--fixture` flag.  The archetype provides the `domainapp.fixture.scenarios.RecreateSimpleObjects` fixture script, for example:
 
@@ -149,7 +149,7 @@ These screenshots are for v1.10.0.
 ====
 
 
-When you start the app, you'll be presented with a welcome page from which you can access the webapp using either the xref:ugvw.adoc#[Wicket viewer] or the xref:ugvro.adoc#[Restful Objects viewer]:
+When you start the app, you'll be presented with a welcome page from which you can access the webapp using either the xref:../ugvw/ugvw.adoc#[Wicket viewer] or the xref:../ugvro/ugvro.adoc#[Restful Objects viewer]:
 
 image::{_imagesdir}getting-started/using-simple-app/010-root-page.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/010-root-page.png"]
 
@@ -158,7 +158,7 @@ The Wicket viewer provides a human usable web UI (implemented, as you might have
 
 image::{_imagesdir}getting-started/using-simple-app/020-login-to-wicket-viewer.png[width="600px",link="{_imagesdir}getting-started/using-simple-app/020-login-to-wicket-viewer.png"]
 
-The app itself is configured to run using xref:ugsec.adoc#[shiro security], as configured in the `WEB-INF/shiro.ini` config file.  You can login with:
+The app itself is configured to run using xref:../ugsec/ugsec.adoc#[shiro security], as configured in the `WEB-INF/shiro.ini` config file.  You can login with:
 
 * username: _sven_
 * password: _pass_
@@ -266,10 +266,10 @@ As noted above, the generated app is a very simple application consisting of a s
 |Domain object fixtures used for initializing the system when being demo'ed or for unit testing.
 
 |`myapp-integtests`
-|End-to-end xref:ugtst.adoc#_ugtst_integ-test-support[integration tests] that exercise from the UI through to the database
+|End-to-end xref:../ugtst/ugtst.adoc#_ugtst_integ-test-support[integration tests] that exercise from the UI through to the database
 
 |`myapp-webapp`
-|Run as a webapp (from `web.xml`) hosting the xref:ugvw.adoc#[Wicket viewer] and/or the xref:ugvro.adoc#[RestfulObjects viewer]
+|Run as a webapp (from `web.xml`) hosting the xref:../ugvw/ugvw.adoc#[Wicket viewer] and/or the xref:../ugvro/ugvro.adoc#[RestfulObjects viewer]
 
 |===
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure.adoc
index e484a74..4e0b7f9 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-Apache Isis works by building a metamodel of the domain objects: entities, xref:ugbtb.adoc#_ugbtb_view-models[view model]s and services.
+Apache Isis works by building a metamodel of the domain objects: entities, xref:../ugbtb/ugbtb.adoc#_ugbtb_view-models[view model]s and services.
 The class methods of both entities and view models represent both state -- (single-valued) properties and (multi-valued) collections -- and behaviour -- actions.  The class members of domain services is simpler: just behaviour, ie actions.
 
 In the automatically generated UI a property is rendered as a field.
@@ -24,7 +24,7 @@ In this section we discuss the mechanics of writing domain objects that comply w
 In fact, the Apache Isis programming model is extensible; you can teach Apache Isis new programming conventions and you can remove existing ones; ultimately they amount to syntax.
 The only real fundamental that can't be changed is the notion that objects consist of properties, collections and actions.
 
-You can learn more about extending Apache Isis programming model xref:ugbtb.adoc#_ugbtb_programming-model[here].
+You can learn more about extending Apache Isis programming model xref:../ugbtb/ugbtb.adoc#_ugbtb_programming-model[here].
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_class-definition.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_class-definition.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_class-definition.adoc
index f88aa9c..70b3659 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_class-definition.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_class-definition.adoc
@@ -22,7 +22,7 @@ Apache Isis recognizes some of the JDO and JAXB annotations and infers domain se
 You can generally recognize an Apache Isis domain class because it will be probably be annotated using `@DomainObject` and `@DomainService`.
 The framework also defines supplementary annotations, `@DomainObjectLayout` and `@DomainServiceLayout`.
 These provide hints relating to the layout of the domain object in the user interface.
-(Alternatively, these UI hints can be defined in a supplementary xref:ugvw.adoc#_ugvw_layout[`.layout.xml`] file.
+(Alternatively, these UI hints can be defined in a supplementary xref:../ugvw/ugvw.adoc#_ugvw_layout[`.layout.xml`] file.
 
 We use Maven modules as a way to group related domain objects together; we can then reason about all the classes in that module as a single unit.
 By convention there will be a single top-level package corresponding to the module.
@@ -167,7 +167,7 @@ There is further discussion of service injection xref:../ugfun/ugfun.adoc#_ugfun
 [[__ugfun_how-tos_class-structure_class-definition_view-models]]
 == View Models
 
-xref:ugbtb.adoc#_ugbtb_view-models[View model]s are similar to entities in that (unlike domain services) there can be many instances of any given type; but they differ from entities in that they are not persisted into a database.
+xref:../ugbtb/ugbtb.adoc#_ugbtb_view-models[View model]s are similar to entities in that (unlike domain services) there can be many instances of any given type; but they differ from entities in that they are not persisted into a database.
 Instead they are recreated dynamically by serializing their state, ultimately into the URL itself.
 
 A common use case for view models is to support a business process.
@@ -177,7 +177,7 @@ Another use case is for a view model to act as a proxy for an entity that is man
 For example, a `Content` view model could represent a PDF that has been scanned and is held within a separate Content Management system.
 
 A third use case is to define DTOs that act as a stable projection of one or more underlying entities.
-Apache Isis' xref:ugvro.adoc[Restful Objects] viewer provides a REST API that then allows REST clients to query the application using these DTOs; useful for integration scenarios.
+Apache Isis' xref:../ugvro/ugvro.adoc[Restful Objects] viewer provides a REST API that then allows REST clients to query the application using these DTOs; useful for integration scenarios.
 
 Apache Isis offers several ways to implement view models, but the most flexible/powerful is to annotate the class using JAXB annotations.
 For example:

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_collections.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_collections.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_collections.adoc
index a01e1de..16a58de 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_collections.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_collections.adoc
@@ -16,7 +16,7 @@ Most collections (those that are modifiable) will also have a setter and (if per
 And collections properties will also have a number of annotations:
 
 * Apache Isis defines its own set own `@Collection` annotation for capturing domain semantics.
-It also provides a `@CollectionLayout` for UI hints (though the information in this annotation may instead be provided by a supplementary xref:ugvw.adoc#_ugvw_layout[`.layout.xml`] file
+It also provides a `@CollectionLayout` for UI hints (though the information in this annotation may instead be provided by a supplementary xref:../ugvw/ugvw.adoc#_ugvw_layout[`.layout.xml`] file
 
 * the collections of domain entities are often annotated with various JDO/DataNucleus annotations, most notable `javax.jdo.annotations.Persistent`.
 This and other annotations can be used to specify if the association is bidirectional, and whether to define a link table or not to hold foreign key columns.
@@ -25,7 +25,7 @@ This and other annotations can be used to specify if the association is bidirect
 
 Apache Isis recognises some of these annotations for JDO/DataNucleus and JAXB and infers some domain semantics from them (for example, the maximum allowable length of a string property).
 
-Unlike xref:../ugfun/ugfun.adoc#_ugfun_how-tos_class-structure_properties[properties], the framework (at least, the xref:ugvw.adoc[Wicket viewer]) does not allow collections to be "edited".
+Unlike xref:../ugfun/ugfun.adoc#_ugfun_how-tos_class-structure_properties[properties], the framework (at least, the xref:../ugvw/ugvw.adoc[Wicket viewer]) does not allow collections to be "edited".
 Instead, xref:../ugfun/ugfun.adoc#_ugfun_how-tos_class-structure_actions[action]s can be written that will modify the contents of the collection as a side-effect.
 For example, a `placeOrder(...)` action will likely add an `Order` to the `Customer#orders` collection.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_properties.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_properties.adoc
index 1c8bd36..5a49a5b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_properties.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_class-structure_properties.adoc
@@ -16,7 +16,7 @@ Most properties (those that are editable/modifiable) will also have a setter and
 And most properties will also have a number of annotations:
 
 * Apache Isis defines its own set own `@Property` annotation for capturing domain semantics.
-It also provides a `@PropertyLayout` for UI hints (though the information in this annotation may instead be provided by a supplementary xref:ugvw.adoc#_ugvw_layout[`.layout.xml`] file
+It also provides a `@PropertyLayout` for UI hints (though the information in this annotation may instead be provided by a supplementary xref:../ugvw/ugvw.adoc#_ugvw_layout[`.layout.xml`] file
 
 * the properties of domain entities are often annotated with the JDO/DataNucleus `@javax.jdo.annotations.Column` annotation.
 For property references, there may be other annotations to indicate whether the reference is bidirectional.
@@ -129,7 +129,7 @@ If this is omitted then whether editing is enabled or disabled is defined global
 [[__ugfun_how-tos_class-structure_properties_ignoring-properties]]
 == Ignoring Properties
 
-By default Apache Isis will automatically render all properties in the xref:ugvw.adoc[UI] or in the xref:ugvro.adoc[REST API].
+By default Apache Isis will automatically render all properties in the xref:../ugvw/ugvw.adoc[UI] or in the xref:../ugvro/ugvro.adoc[REST API].
 To get Apache Isis to ignore a property (exclude it from its metamodel), annotate the getter using `@Programmatic`.
 
 Similarly, you can tell JDO/DataNucleus to ignore a property using the `@javax.jdo.annotations.NotPersistent` annotation.

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_domain-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_domain-services.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_domain-services.adoc
index 4bda8a0..4159152 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_domain-services.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_domain-services.adoc
@@ -173,7 +173,7 @@ public OrderContributions {
 <3> Only actions with a single argument can be contributed as associations
 
 More information about contributions can be found xref:../ugfun/ugfun.adoc#_ugfun_how-tos_contributed-members[here].  More information
-about using contributions and mixins to keep your domain application decoupled can be found xref:ugbtb.adoc#_ugbtb_decoupling_contributions[here] and xref:ugbtb.adoc#_ugbtb_decoupling_mixins[here].
+about using contributions and mixins to keep your domain application decoupled can be found xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_contributions[here] and xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_mixins[here].
 
 
 === Event Subscribers

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_action-icons-and-css.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_action-icons-and-css.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_action-icons-and-css.adoc
index 3a62241..7c15e16 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_action-icons-and-css.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_action-icons-and-css.adoc
@@ -14,7 +14,7 @@ These UI hint can be applied either to individual actions, or can be applied en-
 NOTE: FIXME - xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout#cssClass()`] and xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClassFa[`@ActionLayout#cssClassFa()`]
 
 
-Alternatively, you can specify these hints dynamically in the xref:ugvw.adoc#_ugvw_layout[`Xxx.layout.json`] for the entity.
+Alternatively, you can specify these hints dynamically in the xref:../ugvw/ugvw.adoc#_ugvw_layout[`Xxx.layout.json`] for the entity.
 
 
 == Per pattern matching

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_layout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_layout.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_layout.adoc
index 580a564..a4b02a1 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_layout.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_layout.adoc
@@ -5,5 +5,5 @@
 :_imagesdir: images/
 
 
-See the xref:ugvw.adoc#_ugvw_layout[object layout] chapter.
+See the xref:../ugvw/ugvw.adoc#_ugvw_layout[object layout] chapter.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_names-and-descriptions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_names-and-descriptions.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_names-and-descriptions.adoc
index 17a908a..0b9e432 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_names-and-descriptions.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_names-and-descriptions.adoc
@@ -8,7 +8,7 @@ NOTE: FIXME
 
 
 
-NOTE: see also xref:ugbtb.adoc#_ugbtb_i18n[Internationalization]
+NOTE: see also xref:../ugbtb/ugbtb.adoc#_ugbtb_i18n[Internationalization]
 
 == Class (object)
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_object-titles-and-icons.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_object-titles-and-icons.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_object-titles-and-icons.adoc
index 6af3a1b..3a5b643 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_object-titles-and-icons.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui-hints_object-titles-and-icons.adoc
@@ -9,7 +9,7 @@ In Apache Isis every object is identified to the user by a title (label) and an
 
 The icon is often the same for all instances of a particular class, but it's also possible for an individual instance to return a custom icon.  This could represent the state of that object (eg a shipped order, say, or overdue library book).
 
-It is also possible for an object to provide a CSS class hint.  In conjunction with xref:ugvw.adoc#_ugvw_customisation_tweaking-css-classes[customized CSS] this can be used to apply arbitrary styling; for example each object could be rendered in a page with a different background colour.
+It is also possible for an object to provide a CSS class hint.  In conjunction with xref:../ugvw/ugvw.adoc#_ugvw_customisation_tweaking-css-classes[customized CSS] this can be used to apply arbitrary styling; for example each object could be rendered in a page with a different background colour.
 
 
 == Object Title
@@ -92,6 +92,6 @@ NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_iconName[`iconNam
 == Object CSS Styling
 
 
-It is also possible for an object to return a xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_cssClass[CSS class].  In conjunction with xref:ugvw.adoc#_ugvw_customisation_tweaking-css-classes[customized CSS] this can be used to apply arbitrary styling; for example each object could be rendered in a page with a different background colour.
+It is also possible for an object to return a xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_cssClass[CSS class].  In conjunction with xref:../ugvw/ugvw.adoc#_ugvw_customisation_tweaking-css-classes[customized CSS] this can be used to apply arbitrary styling; for example each object could be rendered in a page with a different background colour.
 
 NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_cssClass[`cssClass()`], xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_cssClass[`@DomainObjectLayout#cssClass()`] xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout#cssClass()`], xref:../rgant/rgant.adoc#_rgant-PropertyLayout_cssClass[`@PropertyLayout#cssClass()`], xref:../rgant/rgant.adoc#_rgant-CollectionLayout_cssClass[`@CollectionLayout#cssClass()`]

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui_are-you-sure.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui_are-you-sure.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui_are-you-sure.adoc
index 06dc559..7c24458 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui_are-you-sure.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_how-tos_ui_are-you-sure.adoc
@@ -42,7 +42,7 @@ image::{_imagesdir}/how-tos/tips-n-tricks/are-you-sure.png[]
 
 [NOTE]
 ====
-Note that these screenshots shows an earlier version of the xref:ugvw.adoc#[Wicket viewer] UI (specifically, pre 1.8.0).
+Note that these screenshots shows an earlier version of the xref:../ugvw/ugvw.adoc#[Wicket viewer] UI (specifically, pre 1.8.0).
 ====
 
 If the user checks the box:

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugfun/ugfun.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/ugfun.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/ugfun.adoc
index 6a30398..e838c6e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/ugfun.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/ugfun.adoc
@@ -13,7 +13,7 @@ This guide introduces the xref:../ugfun/ugfun.adoc#_ugfun_core-concepts[core con
 and tells you how to xref:../ugfun/ugfun.adoc#_ugfun_getting-started[get started] with a Maven archetype.
 
 It also describes a number of xref:../ugfun/ugfun.adoc#_ugfun_how-tos[how-to]s, describes how to influence the
-xref:ugvw.adoc#_ugvw_layout[UI layout] of your domain objects (this is ultimately just a type of metadata), and it
+xref:../ugvw/ugvw.adoc#_ugvw_layout[UI layout] of your domain objects (this is ultimately just a type of metadata), and it
  catalogues various xref:../dg/dg.adoc#_dg_hints-and-tips.adoc[FAQ]s.
 
 === Other Guides

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring.adoc
index 3681912..1734c98 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring.adoc
@@ -8,7 +8,7 @@ Apache Isis programmatically configures DataNucleus; any Apache Isis properties
 
 DataNucleus will for itself also and read the `META-INF/persistence.xml`; at a minimum this defines the name of the "persistence unit".  n theory it could also hold mappings, though in Apache Isis we tend to use annotations instead.
 
-Furthermore, DataNucleus will search for various other XML mapping files, eg `mappings.jdo`.  A full list can be found http://www.datanucleus.org/products/datanucleus/jdo/metadata.html[here].  The metadata in these XML can be used to override the annotations of annotated entities; see xref:ugbtb.adoc#_ugbtb_other-techniques_overriding-jdo-annotations[Overriding JDO Annotatons] for further discussion.
+Furthermore, DataNucleus will search for various other XML mapping files, eg `mappings.jdo`.  A full list can be found http://www.datanucleus.org/products/datanucleus/jdo/metadata.html[here].  The metadata in these XML can be used to override the annotations of annotated entities; see xref:../ugbtb/ugbtb.adoc#_ugbtb_other-techniques_overriding-jdo-annotations[Overriding JDO Annotatons] for further discussion.
 
 
 include::_ugodn_configuring_properties.adoc[leveloffset=+1]

[05/58] [abbrv] isis git commit: ISIS-1521: fixes xref links between guides

[da...@apache.org]

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_metadata-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_metadata-api.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_metadata-api.adoc
index aa2b014..3a3a52e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_metadata-api.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_metadata-api.adoc
@@ -20,7 +20,7 @@ The table below summarizes the metadata APIs defined by Apache Isis.  It also li
 |Notes
 
 
-|xref:rgsvc.adoc#_rgsvc_api_ApplicationFeatureRepository[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ApplicationFeatureRepository[`o.a.i.applib.` +
 `services.appfeat` +
 `ApplicationFeatureRepository`]
 |Provides access to string representations of the features (package, class, class members) of the domain classes
@@ -32,7 +32,7 @@ within the metamodel.
 
 
 
-|xref:rgsvc.adoc#_rgsvc_api_LayoutService[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_api_LayoutService[`o.a.i.applib.` +
 `services.layout` +
 `LayoutService`]
 |Provides the ability to download `Xxx.layout.xml` files, in various styles.
@@ -44,7 +44,7 @@ within the metamodel.
 
 
 
-|xref:rgsvc.adoc#_rgsvc_api_MetaModelService[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_api_MetaModelService[`o.a.i.applib.` +
 `services.metamodel` +
 `MetaModelService`]
 |Access to certain information from the Apache Isis metamodel.
@@ -54,7 +54,7 @@ within the metamodel.
 |Functionality surfaced in the UI through related menu.
 
 
-|xref:rgsvc.adoc#_rgsvc_api_ServiceRegistry[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ServiceRegistry[`o.a.i.applib.` +
 `services.registry` +
 `ServiceRegistry`]
 |Methods to access and use other domain services.
@@ -62,19 +62,19 @@ within the metamodel.
 ``Default`` +
 ``o.a.i.core`` +
 ``isis-core-metamodel``
-|Supercedes methods in xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`].
+|Supercedes methods in xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`].
 
 
 
 
-|xref:rgsvc.adoc#_rgsvc_api_SwaggerService[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_api_SwaggerService[`o.a.i.applib.` +
 `services.swagger` +
 `SwaggerService`]
 |Generates link:http://swagger.io/[Swagger] spec files to describe the public and/or private RESTful APIs exposed by the xref:ugvro.adoc#[RestfulObjects viewer].  These can then be used with the link:http://swagger.io/swagger-ui/[Swagger UI] page to explore the REST API, or used to generate client-side stubs using the link:http://swagger.io/swagger-codegen/[Swagger codegen] tool, eg for use in a custom REST client app.
 |`SwaggerServiceDefault` +
 ``o.a.i.core`` +
 ``isis-core-metamodel``
-|A `SwaggerServiceMenu` domain service is also provided which enables the swagger spec to be downloaded.  Apache Isis' xref:rgmvn.adoc[Maven plugin] also provides a xref:rgmvn.adoc#_rgmvn_swagger[swagger goal] which allows the spec file(s) to be generated at build time (eg so that client-side stubs can then be generated in turn).
+|A `SwaggerServiceMenu` domain service is also provided which enables the swagger spec to be downloaded.  Apache Isis' xref:../rgmvn/rgmvn.adoc[Maven plugin] also provides a xref:../rgmvn/rgmvn.adoc#_rgmvn_swagger[swagger goal] which allows the spec file(s) to be generated at build time (eg so that client-side stubs can then be generated in turn).
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_persistence-layer-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_persistence-layer-api.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_persistence-layer-api.adoc
index cf2522f..7362ebe 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_persistence-layer-api.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_persistence-layer-api.adoc
@@ -22,7 +22,7 @@ The table below summarizes the persistence layer APIs defined by Apache Isis.  I
 |Notes
 
 
-|xref:rgsvc.adoc#_rgsvc_api_IsisJdoSupport[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_api_IsisJdoSupport[`o.a.i.applib.` +
 `services.jdosupport` +
 `IsisJdoSupport`]
 |Lower level access to the JDO Persistence API.
@@ -32,7 +32,7 @@ The table below summarizes the persistence layer APIs defined by Apache Isis.  I
 |
 
 
-|xref:rgsvc.adoc#_rgsvc_api_MetricsService[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_api_MetricsService[`o.a.i.applib.` +
 `services.metrics` +
 `MetricsService`]
 |Gathers and provides metrics on the numbers of objects used within a transaction.
@@ -42,7 +42,7 @@ The table below summarizes the persistence layer APIs defined by Apache Isis.  I
 |
 
 
-|xref:rgsvc.adoc#_rgsvc_api_QueryResultsCache[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_api_QueryResultsCache[`o.a.i.applib.` +
 `services.` +
 `queryresultscache` +
 `QueryResultsCache`]
@@ -54,7 +54,7 @@ The table below summarizes the persistence layer APIs defined by Apache Isis.  I
 
 
 
-|xref:rgsvc.adoc#_rgsvc_api_RepositoryService[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_api_RepositoryService[`o.a.i.applib.` +
 `services.repository` +
 `RepositoryService`]
 |Methods to help implement repositories: query for existing objects, persist new or delete existing objects
@@ -62,7 +62,7 @@ The table below summarizes the persistence layer APIs defined by Apache Isis.  I
 ``Default`` +
 ``o.a.i.core`` +
 ``isis-core-metamodel``
-|Supercedes methods in xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`].
+|Supercedes methods in xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`].
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_persistence-layer-spi.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_persistence-layer-spi.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_persistence-layer-spi.adoc
index 99bc259..22a389d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_persistence-layer-spi.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_persistence-layer-spi.adoc
@@ -23,7 +23,7 @@ The table below summarizes the persistence layer SPIs defined by Apache Isis.  I
 
 
 
-|xref:rgsvc.adoc#_rgsvc_spi_AuditingService[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditingService[`o.a.i.applib.` +
 `services.audit` +
 `AuditerService`]
 |Create an audit record for every changed property of every changed object within a transaction.
@@ -35,19 +35,19 @@ also +
 |
 
 
-|xref:rgsvc.adoc#_rgsvc_spi_AuditingService[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditingService[`o.a.i.applib.` +
 `services.audit` +
 `AuditingService3`]
-|(deprecated, replaced by xref:rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditerService`]); creates
+|(deprecated, replaced by xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditerService`]); creates
 an audit record for every changed property of every changed object within a transaction.
 |
 |
 
 
-|xref:rgsvc.adoc#_rgsvc_spi_EventSerializer[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_EventSerializer[`o.a.i.applib.` +
 `services.publish` +
 `EventSerializer`]
-|(deprecated, not used by replacement xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`]) Creates a representation of either an action invocation or a changed object being published through the xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`].
+|(deprecated, not used by replacement xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`]) Creates a representation of either an action invocation or a changed object being published through the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`].
 |`RestfulObjects-` +
 `SpecEventSerializer` +
 ``o.ia.m.publishing`` +
@@ -56,7 +56,7 @@ an audit record for every changed property of every changed object within a tran
 
 
 
-|xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublisherService[`o.a.i.applib.` +
 `services.publish` +
 `PublisherService`]
 |Publish any action invocations/property edits and changed objects, typically for interchange with an external system in a different bounded context.
@@ -70,10 +70,10 @@ also +
 |
 
 
-|xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublishingService[`o.a.i.applib.` +
 `services.publish` +
 `PublishingService`]
-|(deprecated, replaced by xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`]) Publish any action invocations and changed objects, typically for interchange with an external system in a different bounded context.
+|(deprecated, replaced by xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`]) Publish any action invocations and changed objects, typically for interchange with an external system in a different bounded context.
 |`PublishingService` +
 ``o.ia.m.publishing`` +
 ``isis-module-publishing``
@@ -82,7 +82,7 @@ also +
 
 
 
-|xref:rgsvc.adoc#_rgsvc_spi_UserRegistrationService[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UserRegistrationService[`o.a.i.applib.` +
 `services.userreg` +
 `UserRegistrationService`]
 |Create a new user account with the configured security mechanism.
@@ -105,7 +105,7 @@ Key:
 * `o.a.i.c.r.s` is an abbreviation for `org.apache.isis.core.runtime.services`
 
 
-Where an implementation is available (on the classpath) then it is always registered automatically (that is, they are all (with one exception) annotated with xref:rgant.adoc#_rgant-DomainService[`@DomainService`].
+Where an implementation is available (on the classpath) then it is always registered automatically (that is, they are all (with one exception) annotated with xref:../rgant/rgant.adoc#_rgant-DomainService[`@DomainService`].
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_presentation-layer-spi.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_presentation-layer-spi.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_presentation-layer-spi.adoc
index e6ff519..6c0ed69 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_presentation-layer-spi.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_presentation-layer-spi.adoc
@@ -21,7 +21,7 @@ The table below summarizes the presentation layer SPIs defined by Apache Isis.
 |Notes
 
 
-|xref:rgsvc.adoc#_rgsvc_spi_ContentMappingService[`o.a.i.applb.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ContentMappingService[`o.a.i.applb.` +
 `services.conmap` +
 `ContentMappingService`]
 |(Attempt to) map the returned data into the representation required by the client's HTTP `Accept` header.
@@ -33,10 +33,10 @@ No default implementation.
 
 
 
-|xref:rgsvc.adoc#_rgsvc_spi_EmailNotificationService[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_EmailNotificationService[`o.a.i.applib.` +
 `services.userreg` +
 `EmailNotificationService`]
-|Notify a user during xref:rgsvc.adoc#_rgsvc_spi_UserRegistrationService[self-registration] of users.
+|Notify a user during xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UserRegistrationService[self-registration] of users.
 |`EmailNotificationService-` +
 `Default` +
 ``o.a.i.core`` +
@@ -45,7 +45,7 @@ No default implementation.
 a configured `EmailService`
 
 
-|xref:rgsvc.adoc#_rgsvc_spi_ErrorReportingService[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ErrorReportingService[`o.a.i.applib.` +
 `services.error` +
 `ErrorReportingService`]
 |Record details of an error occurring in the system (eg in an external incident recording system such as JIRA), and return a more friendly (jargon-free) message to display to the end user, with optional reference (eg `XXX-1234`).
@@ -53,7 +53,7 @@ a configured `EmailService`
 |
 
 
-|xref:rgsvc.adoc#_rgsvc_spi_ExceptionRecognizer[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ExceptionRecognizer[`o.a.i.applib.` +
 `services.exceprecog` +
 `ExceptionRecognizer2`]
 |Convert certain exceptions (eg foreign or unique key violation in the database) into a format that can be rendered to the end-user.
@@ -65,7 +65,7 @@ a configured `EmailService`
 |Extensible using composite pattern if required
 
 
-|xref:rgsvc.adoc#_rgsvc_spi_GridSystemService[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_GridSystemService[`o.a.i.applib.` +
 `services.grid` +
 `GridSystemService`]
 |Validates and normalizes the grid layout for a domain class (with respect to a particular grid
@@ -76,7 +76,7 @@ system such as Bootstrap3), also providing a default grid (for those domain clas
 |
 
 
-|xref:rgsvc.adoc#_rgsvc_spi_GridLoaderService[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_GridLoaderService[`o.a.i.applib.` +
 `services.grid` +
 `GridLoaderService`]
 |Responsible for loading a grid layout for a domain class, eg from a `layout.xml` file.
@@ -86,11 +86,11 @@ system such as Bootstrap3), also providing a default grid (for those domain clas
 |
 
 
-|xref:rgsvc.adoc#_rgsvc_spi_GridService[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_GridService[`o.a.i.applib.` +
 `services.grid` +
 `GridService`]
-|A facade on top of both xref:rgsvc.adoc#_rgsvc_spi_GridLoaderService[`GridLoaderService`] and
-xref:rgsvc.adoc#_rgsvc_spi_GridSystemService[`GridSystemService`], thus being able to return normalized
+|A facade on top of both xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_GridLoaderService[`GridLoaderService`] and
+xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_GridSystemService[`GridSystemService`], thus being able to return normalized
 grids for any domain class.
 |`GridServiceDefault` +
 ``o.a.i.core`` +
@@ -98,7 +98,7 @@ grids for any domain class.
 |
 
 
-|xref:rgsvc.adoc#_rgsvc_spi_HintStore[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_HintStore[`o.a.i.applib.` +
 `services.hint` +
 `HintStore`]
 |Stores UI hints on a per-object basis. For example, the viewer remembers which tabs are selected, and for collections which view is selected (eg table or hidden), which page of a table to render, or whether "show all" (rows) is toggled.
@@ -108,29 +108,29 @@ grids for any domain class.
 |
 
 
-|xref:rgsvc.adoc#_rgsvc_spi_LocaleProvider[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_LocaleProvider[`o.a.i.applib.` +
 `services.i18n` +
 `LocaleProvider`]
-|Request-scoped service to return the locale of the current user, in support of i18n (ie so that the app's UI, messages and exceptions can be translated to the required locale by the xref:rgsvc.adoc#_rgsvc_spi_TranslationService[`TranslationService`].
+|Request-scoped service to return the locale of the current user, in support of i18n (ie so that the app's UI, messages and exceptions can be translated to the required locale by the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_TranslationService[`TranslationService`].
 |`LocaleProviderWicket` +
 ``o.a.i.viewer`` +
 ``isis-viewer-wicket-impl``
 |
 
 
-|xref:rgsvc.adoc#_rgsvc_spi_RoutingService[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_RoutingService[`o.a.i.applib.` +
 `services.routing` +
 `RoutingService`]
 |Return an alternative object than that returned by an action.
 |`RoutingServiceDefault` +
 ``o.a.i.core`` +
 ``isis-core-applib``
-|The default implementation will return the home page (per xref:rgsvc.adoc#_rgsvc_api_HomePageProviderService[`HomePageProviderService`]) if a void or null is returned. +
+|The default implementation will return the home page (per xref:../rgsvc/rgsvc.adoc#_rgsvc_api_HomePageProviderService[`HomePageProviderService`]) if a void or null is returned. +
 Used by the xref:ugvw.adoc#[Wicket viewer] only.
 
 
 
-|xref:rgsvc.adoc#_rgsvc_spi_TableColumnOrderService[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_TableColumnOrderService[`o.a.i.applib.` +
 `services.tablecol` +
 `TableColumn-` +
 `OrderService`]
@@ -142,10 +142,10 @@ Used by the xref:ugvw.adoc#[Wicket viewer] only.
 |
 
 
-|xref:rgsvc.adoc#_rgsvc_spi_TranslationService[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_TranslationService[`o.a.i.applib.` +
 `services.i18n` +
 `TranslationService`]
-|Translate an app's UI, messages and exceptions for the current user (as per the locale provided by xref:rgsvc.adoc#_rgsvc_spi_LocaleProvider[`LocalProvider`].
+|Translate an app's UI, messages and exceptions for the current user (as per the locale provided by xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_LocaleProvider[`LocalProvider`].
 |`TranslationServicePo` +
 ``o.a.i.core`` +
 ``isis-core-runtime``
@@ -154,17 +154,17 @@ depends on: +
 `TranslationsResolver`, `LocaleProvider`
 
 
-|xref:rgsvc.adoc#_rgsvc_spi_TranslationsResolver[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_TranslationsResolver[`o.a.i.applib.` +
 `services.i18n` +
 `TranslationsResolver`]
-|Obtain translations for a particuar phrase and locale, in support of i18n (ie so that the app's UI, messages and exceptions can be translated to the required locale by the xref:rgsvc.adoc#_rgsvc_spi_TranslationService[`TranslationService`]
+|Obtain translations for a particuar phrase and locale, in support of i18n (ie so that the app's UI, messages and exceptions can be translated to the required locale by the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_TranslationService[`TranslationService`]
 |`TranslationsResolverWicket` +
 ``o.a.i.viewer`` +
 ``isis-viewer-wicket-impl``
 |
 
 
-|xref:rgsvc.adoc#_rgsvc_spi_UrlEncodingService[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UrlEncodingService[`o.a.i.applib.` +
 `services.urlencoding` +
 `UrlEncodingService`]
 |Converts strings into a form safe for use within a URL.  Used to convert view models mementos into usable URL form.
@@ -176,7 +176,7 @@ depends on: +
 |
 
 
-|xref:rgsvc.adoc#_rgsvc_spi_UserProfileService[`o.a.i.applib.` +
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UserProfileService[`o.a.i.applib.` +
 `services.userprof` +
 `UserProfileService`]
 |Obtain an alternative (usually enriched/customized) name for the current user, to render in the UI.

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_AuditerService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_AuditerService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_AuditerService.adoc
index 37f46fa..e0f435d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_AuditerService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_AuditerService.adoc
@@ -11,7 +11,7 @@ The `AuditerService` auditing service provides a simple mechanism to capture cha
 
 [NOTE]
 ====
-This service is intended to replace the now-deprecated xref:rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService3`].
+This service is intended to replace the now-deprecated xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService3`].
 The difference between the two is that this service recognises that the `transactionId` is now (as of `1.13.0`)
 actually a request/interaction Id, and that an additional `sequence
 ====
@@ -85,7 +85,7 @@ the secondary menu bar.
 the user interface (they are all `@Programmatic`).
 
 * `AuditingServiceContributions` which contrbutes collections to the
-xref:rgcms.adoc#_rgcms_classes_mixins_HasTransactionId[ `HasTransactionId`] interface. This will therefore display all
+xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins_HasTransactionId[ `HasTransactionId`] interface. This will therefore display all
 audit entries that occurred in a given request/transaction, in other words whenever a command, a published event or
 another audit entry is displayed.
 
@@ -94,7 +94,7 @@ another audit entry is displayed.
 
 == Usage
 
-The typical way to indicate that an object should be audited is to annotate it with the xref:rgant.adoc#_rgant-DomainObject_auditing[`@DomainObject#auditing()`] annotation.
+The typical way to indicate that an object should be audited is to annotate it with the xref:../rgant/rgant.adoc#_rgant-DomainObject_auditing[`@DomainObject#auditing()`] annotation.
 
 
 
@@ -105,7 +105,7 @@ The (non-ASF) http://github.com/isisaddons/isis-module-audit[Isis addons' audit]
 this service (`AuditerService`), and also provides a number of related domain services (`AuditingServiceMenu`,
 `AuditingServiceRepository` and `AuditingServiceContributions`).
 
-Assuming that an `AppManifest` is being used to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app])
+Assuming that an `AppManifest` is being used to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app])
 then this can be activated by updating the `pom.xml` and updating the `AppManifest#getModules()` method.
 
 If menu items or contributions are not required in the UI, these can be suppressed either using security or by
@@ -116,19 +116,19 @@ implementing a xref:ugbtb.adoc#_ugbtb_decoupling_vetoing-visibility[vetoing subs
 == Related Services
 
 The auditing service works very well with implementations of
-xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] that persist the ``Interaction.Execution`` objects
-obtained from the xref:rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] service.  The interaction
+xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] that persist the ``Interaction.Execution`` objects
+obtained from the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] service.  The interaction
 execution captures the _cause_ of an interaction (an action was invoked, a property was edited), while the
 `AuditerService` audit entries capture the _effect_ of that interaction in terms of changed state.
 
 [NOTE]
 ====
-Prior to `1.13.0` the xref:rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] performed a similar role,
+Prior to `1.13.0` the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] performed a similar role,
 of capturing the cause.  As of `1.13.0`, ``Command``s are now primarily to capture the _intent_ of an action,
 not the actual action invocation itself.
 ====
 
 The `AuditerService` is intended to replace the (now-deprecated)
-xref:rgsvc.adoc#_rgsvc_spi_AuditingService3[`AuditingService3`], as the latter does not support the concept of multiple
+xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditingService3[`AuditingService3`], as the latter does not support the concept of multiple
 transactions within a single interaction.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_AuditingService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_AuditingService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_AuditingService.adoc
index ddb39de..63ed0f8 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_AuditingService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_AuditingService.adoc
@@ -11,7 +11,7 @@ The `AuditingService3` auditing service provides a simple mechanism to capture c
 
 [NOTE]
 ====
-This service is deprecated, replaced by xref:rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditerService`].
+This service is deprecated, replaced by xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditerService`].
 ====
 
 
@@ -46,7 +46,7 @@ The module also provides:
 
 * `AuditingServiceRepository` service to to search for persisted `AuditEntry``s.  None of its actions are visible in the user interface (they are all `@Programmatic`).
 
-* `AuditingServiceContributions` which contrbutes collections to the xref:rgcms.adoc#_rgcms_classes_mixins_HasTransactionId[ `HasTransactionId`] interface. This will therefore display all audit entries that occurred in a given transaction, in other words whenever a command, a published event or another audit entry is displayed.
+* `AuditingServiceContributions` which contrbutes collections to the xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins_HasTransactionId[ `HasTransactionId`] interface. This will therefore display all audit entries that occurred in a given transaction, in other words whenever a command, a published event or another audit entry is displayed.
 
 
 
@@ -56,7 +56,7 @@ If you just want to debug (writing to stderr), you can instead configure `o.a.i.
 
 == Usage
 
-The typical way to indicate that an object should be audited is to annotate it with the xref:rgant.adoc#_rgant-DomainObject_auditing[`@DomainObject#auditing()`] annotation.
+The typical way to indicate that an object should be audited is to annotate it with the xref:../rgant/rgant.adoc#_rgant-DomainObject_auditing[`@DomainObject#auditing()`] annotation.
 
 
 
@@ -67,7 +67,7 @@ The (non-ASF) http://github.com/isisaddons/isis-module-audit[Isis addons' audit]
 this service (`AuditingService`), and also provides a number of related domain services (`AuditingServiceMenu`,
 `AuditingServiceRepository` and `AuditingServiceContributions`).
 
-Assuming that an `AppManifest` is being used to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app])
+Assuming that an `AppManifest` is being used to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app])
 then this can be activated by updating the `pom.xml` and updating the `AppManifest#getModules()` method.
 
 If menu items or contributions are not required in the UI, these can be suppressed either using security or by
@@ -78,6 +78,6 @@ implementing a xref:ugbtb.adoc#_ugbtb_decoupling_vetoing-visibility[vetoing subs
 == Related Services
 
 This service has been deprecated and replaced by the equivalent
-xref:rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditerService`].
+xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditerService`].
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_BackgroundCommandService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_BackgroundCommandService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_BackgroundCommandService.adoc
index 4257ea5..57ae70e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_BackgroundCommandService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_BackgroundCommandService.adoc
@@ -6,11 +6,11 @@
 
 
 
-The `BackgroundCommandService` (SPI) service supports the xref:rgsvc.adoc#_rgsvc_api_BackgroundService[`BackgroundService`] (API) service, persisting action invocations as commands such that they can subsequently be invoked in the background.
+The `BackgroundCommandService` (SPI) service supports the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BackgroundService[`BackgroundService`] (API) service, persisting action invocations as commands such that they can subsequently be invoked in the background.
 
-The `BackgroundService` is responsible for capturing a memento representing the action invocation, and then hands off to the xref:rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[`BackgroundCommandService`] `BackgroundCommandService` to actually persist it.
+The `BackgroundService` is responsible for capturing a memento representing the action invocation, and then hands off to the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[`BackgroundCommandService`] `BackgroundCommandService` to actually persist it.
 
-The persisting of commands is only half the story; there needs to be a separate process to read the commands and execute them.  The abstract xref:rgsvc.adoc#_rgsvc_api_BackgroundService_BackgroundCommandExecution[`BackgroundCommandExecution`] provides a mechanism to execute such commands.  This can be considered an API, albeit "internal" because the implementation relies on internals of the framework.
+The persisting of commands is only half the story; there needs to be a separate process to read the commands and execute them.  The abstract xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BackgroundService_BackgroundCommandExecution[`BackgroundCommandExecution`] provides a mechanism to execute such commands.  This can be considered an API, albeit "internal" because the implementation relies on internals of the framework.
 
 
 
@@ -31,7 +31,7 @@ public interface BackgroundCommandService {
 
 }
 ----
-<1> is a wrapper around a xref:rgsvc.adoc#_rgsvc_api_MementoService[`MementoService`]'s `Memento`, capturing the details of the action invocation to be retained (eg persisted to a database) so that it can be executed at a later time
+<1> is a wrapper around a xref:../rgsvc/rgsvc.adoc#_rgsvc_api_MementoService[`MementoService`]'s `Memento`, capturing the details of the action invocation to be retained (eg persisted to a database) so that it can be executed at a later time
 <2> reference to the parent `Command` requesting the action be performed as a background command.  This allows information such as the initiating user to be obtained.
 
 The API of `ActionInvocationMemento` in turn is:
@@ -85,7 +85,7 @@ The module also provides a concrete subclass of `BackgroundCommandExecution` tha
 
 [TIP]
 ====
-Details of setting up the Quartz scheduler to actually execute these persisted commands can be found on the xref:rgsvc.adoc#_rgsvc_api_BackgroundService[`BackgroundService`] page.
+Details of setting up the Quartz scheduler to actually execute these persisted commands can be found on the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BackgroundService[`BackgroundService`] page.
 ====
 
 
@@ -95,9 +95,9 @@ Details of setting up the Quartz scheduler to actually execute these persisted c
 
 Background commands can be created either declaratively or imperatively.
 
-The declarative approach involves annotating an action using xref:rgant.adoc#_rgant-Action_command[`@Action#command()`] with `@Action#commandExecuteIn=CommandExecuteIn.BACKGROUND`.
+The declarative approach involves annotating an action using xref:../rgant/rgant.adoc#_rgant-Action_command[`@Action#command()`] with `@Action#commandExecuteIn=CommandExecuteIn.BACKGROUND`.
 
-The imperative approach involves explicitly calling the xref:rgsvc.adoc#_rgsvc_api_BackgroundService[`BackgroundService`] from within domain object's action.
+The imperative approach involves explicitly calling the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BackgroundService[`BackgroundService`] from within domain object's action.
 
 
 
@@ -108,9 +108,9 @@ The (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' comm
 of this service (`BackgroundCommandService`), and also provides a number of related domain services
 (`BackgroundCommandServiceJdo`, `BackgroundCommandJdoRepository` and `BackgroundCommandServiceJdoContributions`).  This
 module also provides service implementations of the
-xref:rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`].
+xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`].
 
-Assuming that an `AppManifest` is being used to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app])
+Assuming that an `AppManifest` is being used to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app])
 then this can be activated by updating the `pom.xml` and updating the `AppManifest#getModules()` method.
 
 If contributions are not required in the UI, these can be suppressed either using security or by implementing a
@@ -122,9 +122,9 @@ xref:ugbtb.adoc#_ugbtb_decoupling_vetoing-visibility[vetoing subscriber].
 
 == Related Services
 
-As discussed above, this service supports the xref:rgsvc.adoc#_rgsvc_api_BackgroundService[`BackgroundService`] , persisting `Command`s such that they can be executed in the background.
+As discussed above, this service supports the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BackgroundService[`BackgroundService`] , persisting `Command`s such that they can be executed in the background.
 
-There is also a tie-up with the xref:rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`] and its supporting xref:rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] domain service. The `CommandContext` service is responsible for providing a parent `Command` with which the background `Command`s can then be associated as children, while the `CommandService` is responsible for persisting those parent `Command`s (analogous to the way in which the `BackgroundCommandService` persists the child background `Command`s). The `BackgroundCommandService` ensures that these background `Command`s are associated with the parent "foreground" `Command`.
+There is also a tie-up with the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`] and its supporting xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] domain service. The `CommandContext` service is responsible for providing a parent `Command` with which the background `Command`s can then be associated as children, while the `CommandService` is responsible for persisting those parent `Command`s (analogous to the way in which the `BackgroundCommandService` persists the child background `Command`s). The `BackgroundCommandService` ensures that these background `Command`s are associated with the parent "foreground" `Command`.
 
 What that means is that the implementations of `CommandService` and `BackgroundCommandService` go together, hence both implemented in the (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module.).
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_ClassDiscoveryService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_ClassDiscoveryService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_ClassDiscoveryService.adoc
index 087587f..8308765 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_ClassDiscoveryService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_ClassDiscoveryService.adoc
@@ -8,7 +8,7 @@
 
 The `ClassDiscovery` service is used to automatically discover subclasses of any given type on the classpath.  The primary use case is to support "convention-over-configuration" designs that work with a minimum of configuration.
 
-This service is used by the xref:rgcms.adoc#_rgcms_classes_super_FixtureScripts[`FixtureScripts`] service to automatically locate any xref:rgcms.adoc#_rgcms_classes_super_FixtureScript[`FixtureScript`] implementations.
+This service is used by the xref:../rgcms/rgcms.adoc#_rgcms_classes_super_FixtureScripts[`FixtureScripts`] service to automatically locate any xref:../rgcms/rgcms.adoc#_rgcms_classes_super_FixtureScript[`FixtureScript`] implementations.
 
 
 
@@ -36,7 +36,7 @@ Isis provides an implementation of this service, namely `o.a.i.applib.services.c
 
 [NOTE]
 ====
-This implementation is also used to discover domain services annotated with xref:rgant.adoc#_rgant-DomainService[`@DomainService`].  Currently this logic uses the implementation directly, so is not pluggable.  However, the entire `ServicesInstaller`
+This implementation is also used to discover domain services annotated with xref:../rgant/rgant.adoc#_rgant-DomainService[`@DomainService`].  Currently this logic uses the implementation directly, so is not pluggable.  However, the entire `ServicesInstaller`
 ====
 
 
@@ -44,9 +44,9 @@ This implementation is also used to discover domain services annotated with xref
 == Usage
 
 The usage will vary depending upon the conventions of the design.  As of 1.9.0, the usage of the service has been
-centralized such that the packages to be scanned are located from the xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`]'s `#getModules()` method.
+centralized such that the packages to be scanned are located from the xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`]'s `#getModules()` method.
 
-For example, the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]'s app manifest includes:
+For example, the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]'s app manifest includes:
 
 [source,java]
 ----
@@ -71,12 +71,12 @@ Other usages of the `ClassDiscoveryService` are likely to work in a similar way,
 == Registering the Services
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
 implementation of `ClassDiscoveryService2` service is automatically registered and injected (it is annotated with
 `@DomainService`) so no further configuration is required.
 
 To use an alternative implementation, use
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
+xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+in the xref:../rgsvc/rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_CommandService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_CommandService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_CommandService.adoc
index 25fc5f8..f211af1 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_CommandService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_CommandService.adoc
@@ -6,28 +6,28 @@
 
 
 
-The `CommandService` service supports the xref:rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`] service such
+The `CommandService` service supports the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`] service such
 that `Command` objects (that reify the invocation of an action/edit of a property on a domain object) can be persisted.
 
 As of `1.13.0`, the primary use case for persistent ``Command``s is in support of background commands; they
 act as a parent to any background commands that can be persisted either explicitly using the
-xref:rgsvc.adoc#_rgsvc_api_BackgroundService[`BackgroundService`], or implicitly by way of the
-xref:rgant.adoc#_rgant-Action_command[`@Action#command()`] annotation.
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BackgroundService[`BackgroundService`], or implicitly by way of the
+xref:../rgant/rgant.adoc#_rgant-Action_command[`@Action#command()`] annotation.
 
 In previous versions of the framework, persistent ``Command``s also supported a number of other use cases:
 
 * they enable profiling of the running application (which actions are invoked then most often, what is their response time)
-* if xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] or
-xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`] (latter deprecated) is configured, they provide
+* if xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] or
+xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`] (latter deprecated) is configured, they provide
 better traceability as the `Command` is also correlated with any published events, again through the unique
 `transactionId` GUID
-* if xref:rgsvc.adoc#_rgsvc_spi_AuderService[`AuditerService`] or
-xref:rgsvc.adoc#_rgsvc_spi_AuditService[`AuditingService`] (latter deprecated) is configured, they provide better audit
+* if xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuderService[`AuditerService`] or
+xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditService[`AuditingService`] (latter deprecated) is configured, they provide better audit
 information, since the `Command` (the 'cause' of an action) can be correlated to the audit records (the "effect" of
 the action) through the `transactionId` GUID
 
 As of `1.13.0`, these other uses cases are now more fully supported through the
-xref:rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] service and persistent implementations of the
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] service and persistent implementations of the
 ``Interaction`` object, eg as provided by the (non-ASF)
 http://github.com/isisaddons/isis-module-publishmq[Isis addons' publishmq] module.
 
@@ -60,7 +60,7 @@ public interface CommandService {
 }
 ----
 <1> Instantiate the appropriate instance of the `Command` (as defined by the
-xref:rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`] service).  Its members will be populated automatically by
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`] service).  Its members will be populated automatically by
 the framework.
 <2> this method (as of `1.13.0`) is *NO LONGER CALLED* and is deprecated: the framework automatically populates the ``Command``'s `timestamp`,
 `user` and `transactionId` fields, so there is no need for the service implementation to initialize any of these.  In
@@ -84,7 +84,7 @@ The (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' comm
 
 == Usage
 
-The typical way to indicate that an action should be reified into a `Command` is by annotating the action using xref:rgant.adoc#_rgant-Action_command[`@Action#command()`].
+The typical way to indicate that an action should be reified into a `Command` is by annotating the action using xref:../rgant/rgant.adoc#_rgant-Action_command[`@Action#command()`].
 
 
 
@@ -95,9 +95,9 @@ The (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' comm
 of this service (`CommandService`), and also provides a number of related domain services
 (`CommandJdoRepository` and `CommandServiceJdoContributions`).  This
 module also provides service implementations of the
-xref:rgsvc.adoc#_rgsvc_spi_CommandService[`BackgroundCommandService`].
+xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_CommandService[`BackgroundCommandService`].
 
-Assuming that an `AppManifest` is being used to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app])
+Assuming that an `AppManifest` is being used to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app])
 then this can be activated by updating the `pom.xml` and updating the `AppManifest#getModules()` method.
 
 If contributions are not required in the UI, these can be suppressed either using security or by implementing a
@@ -108,14 +108,14 @@ xref:ugbtb.adoc#_ugbtb_decoupling_vetoing-visibility[vetoing subscriber].
 
 == Related Services
 
-As discussed above, this service supports the xref:rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`], providing the ability for `Command` objects to be
-persisted. This is closely related to the xref:rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[`BackgroundCommandService`]that allows the xref:rgsvc.adoc#_rgsvc_api_BackgroundService[`BackgroundService`] to schedule commands for background/asynchronous execution.
+As discussed above, this service supports the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`], providing the ability for `Command` objects to be
+persisted. This is closely related to the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[`BackgroundCommandService`]that allows the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BackgroundService[`BackgroundService`] to schedule commands for background/asynchronous execution.
 
 The implementations of `CommandService` and `BackgroundCommandService` are intended to go together, so that persistent parent `Command`s can be associated with their child background `Command`s.
 
-The services provided by this module combines very well with the xref:rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`].  The `CommandService` captures the _cause_ of an interaction (an action was invoked, a property was edited), while the `AuditingService3` captures the _effect_ of that interaction in terms of changed state.
+The services provided by this module combines very well with the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`].  The `CommandService` captures the _cause_ of an interaction (an action was invoked, a property was edited), while the `AuditingService3` captures the _effect_ of that interaction in terms of changed state.
 
-You may also want to configure the xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`].
+You may also want to configure the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`].
 
-All three of these services collaborate implicitly by way of the xref:rgcms.adoc#_rgcms_classes_mixins_HasTransactionId[`HasTransactionId`] interface.
+All three of these services collaborate implicitly by way of the xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins_HasTransactionId[`HasTransactionId`] interface.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_ContentMappingService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_ContentMappingService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_ContentMappingService.adoc
index 43639cf..bb21807 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_ContentMappingService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_ContentMappingService.adoc
@@ -7,11 +7,11 @@
 
 
 The `ContentMappingService` supports the (default implementation of the)
-xref:rgfis.adoc#_rgfis_spi_ContentNegotiationService[`ContentNegotiationService`] allowing the
+xref:../rgfis/rgfis.adoc#_rgfis_spi_ContentNegotiationService[`ContentNegotiationService`] allowing the
 xref:ugvro.adoc#[RestfulObjects viewer] to allow domain objects to be transformed into some other format as specified
 by the HTTP `Accept` header.
 
-See xref:rgfis.adoc#_rgfis_spi_ContentNegotiationService[`ContentNegotiationService`] for further discussion.
+See xref:../rgfis/rgfis.adoc#_rgfis_spi_ContentNegotiationService[`ContentNegotiationService`] for further discussion.
 
 
 [NOTE]
@@ -19,7 +19,7 @@ See xref:rgfis.adoc#_rgfis_spi_ContentNegotiationService[`ContentNegotiationServ
 Unlike most other domain services, the framework (that is, `ContentNegotiationService`) will check _all_ available
 implementations of `ContentMappingService` to convert the domain object to the requested media type, rather than merely
 the first implementation found; in other words it uses the chain-of-responsibility pattern.  Services are checked
-in the ordering defined by xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`]).
+in the ordering defined by xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`]).
 The mapped object used will be the first non-`null` result returned by an implementation.
 ====
 
@@ -99,4 +99,4 @@ public class ContentMappingServiceForToDoItem implements ContentMappingService {
 
 == Related Services
 
-This service is a companion to the default implementation of the xref:rgfis.adoc#_rgfis_spi_ContentNegotiationService[`ContentNegotiationService`].
\ No newline at end of file
+This service is a companion to the default implementation of the xref:../rgfis/rgfis.adoc#_rgfis_spi_ContentNegotiationService[`ContentNegotiationService`].
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_EmailNotificationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_EmailNotificationService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_EmailNotificationService.adoc
index 9aaabd5..1bab3a1 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_EmailNotificationService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_EmailNotificationService.adoc
@@ -8,11 +8,11 @@
 
 The `EmailNotificationService` supports the xref:ugvw.adoc#_ugvw_features_user-registration[user registration] (self sign-up) features of the xref:ugvw.adoc#[Wicket viewer] whereby a user can sign-up to access an application by providing a valid email address.
 
-The Wicket viewer will check whether an implementation of this service (and also the xref:rgsvc.adoc#_rgsvc_spi_UserRegistrationService[`UserRegistrationService`]) is available, and if so will (unless configured not to) expose a sign-up page where the user enters their email address. A verification email is sent using this service; the email includes a link back to the running application. The user then completes the registration process (choosing a user name, password and so on) and the Wicket viewer creates an account for them (using the aforementioned `UserRegistrationService`).
+The Wicket viewer will check whether an implementation of this service (and also the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UserRegistrationService[`UserRegistrationService`]) is available, and if so will (unless configured not to) expose a sign-up page where the user enters their email address. A verification email is sent using this service; the email includes a link back to the running application. The user then completes the registration process (choosing a user name, password and so on) and the Wicket viewer creates an account for them (using the aforementioned `UserRegistrationService`).
 
 The role of this service in all of this is to format and send out emails for the initial registration, or for password resets.
 
-The default implementation of this service uses the xref:rgsvc.adoc#_rgsvc_api_EmailService[`EmailService`], which must be configured in order for user registration to be enabled.
+The default implementation of this service uses the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EmailService[`EmailService`], which must be configured in order for user registration to be enabled.
 
 
 == SPI
@@ -64,18 +64,18 @@ To ensure that your alternative implementation takes the place of the default im
 == Registering the Service
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' default
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' default
 implementation of `EmailNotificationService` service is automatically registered and injected (it is annotated with
 `@DomainService`) so no further configuration is required.
 
 To use an alternative implementation, use
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
+xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+in the xref:../rgsvc/rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
 
 
 == Related Services
 
-As noted elsewhere, the default implementation of this service uses xref:rgsvc.adoc#_rgsvc_api_EmailService[`EmailService`].  This service has no specific configuration properties but does require that the `EmailService` has been configured.
+As noted elsewhere, the default implementation of this service uses xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EmailService[`EmailService`].  This service has no specific configuration properties but does require that the `EmailService` has been configured.
 
-Conversely, this service is used by (Isis' default implementation of) xref:rgsvc.adoc#_rgsvc_spi_UserRegistrationService[`UserRegistrationService`].
+Conversely, this service is used by (Isis' default implementation of) xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UserRegistrationService[`UserRegistrationService`].
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_ErrorReportingService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_ErrorReportingService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_ErrorReportingService.adoc
index 1b6b162..90ca1e9 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_ErrorReportingService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_ErrorReportingService.adoc
@@ -34,8 +34,8 @@ public class ErrorDetails {
     public List<String> getStackTraceDetailList() { // <4>
 }
 ----
-<1> the main message to be displayed to the end-user.  The service is responsible for translating this into the language of the end-user (it can use xref:rgsvc.adoc#_rgsvc_spi_LocaleProvider[`LocaleProvider`] if required).
-<2> whether this message has already been recognized by an xref:rgsvc.adoc#_rgsvc_spi_ExceptionRecognizer[`ExceptionRecognizer`] service.  Generally this converts potentially non-recoverable (fatal) exceptions into recoverable exceptions (warnings) as well providing an alternative mechanism for generating user-friendly error messages.
+<1> the main message to be displayed to the end-user.  The service is responsible for translating this into the language of the end-user (it can use xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_LocaleProvider[`LocaleProvider`] if required).
+<2> whether this message has already been recognized by an xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ExceptionRecognizer[`ExceptionRecognizer`] service.  Generally this converts potentially non-recoverable (fatal) exceptions into recoverable exceptions (warnings) as well providing an alternative mechanism for generating user-friendly error messages.
 <3> whether the cause of the exception was due to a lack of privileges.  In such cases the UI restricts the information shown to the end-user, to avoid leaking potentially sensitive information
 <4> the stack trace of the exception, including the trace of any exceptions in the causal chain.  These technical details are hidden from the user and only shown for non-recoverable exceptions.
 
@@ -100,7 +100,7 @@ image::{_imagesdir}reference-services-spi/ErrorReportingService/kitchensink-exam
 == Registering the Services
 
 There is no default implementation of this service.  To register your own implementation (and assuming that an
-`AppManifest` is being used to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]), then just
+`AppManifest` is being used to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]), then just
 ensure that the implementation is on the classpath and the module containing the implementation is returned in
 `AppManifest#getModules()`.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_EventSerializer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_EventSerializer.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_EventSerializer.adoc
index e226b6c..ba522cd 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_EventSerializer.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_EventSerializer.adoc
@@ -5,14 +5,14 @@
 :_imagesdir: images/
 
 
-The `EmailSerializer` service is a supporting service intended for use by (any implementation of) xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`].  Its responsibility is to combine the `EventMetadata` and the `EventPayload` into some serialized form (such as JSON, XML or a string) that can then be published.
+The `EmailSerializer` service is a supporting service intended for use by (any implementation of) xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`].  Its responsibility is to combine the `EventMetadata` and the `EventPayload` into some serialized form (such as JSON, XML or a string) that can then be published.
 
 [WARNING]
 ====
-This service is deprecated, replaced with xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`].
+This service is deprecated, replaced with xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`].
 ====
 
-See xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`] for further discussion.
+See xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`] for further discussion.
 
 
 
@@ -31,7 +31,7 @@ public interface EventSerializer {
 }
 ----
 <1> returns an object for maximum flexibility, which is then handed off to the `PublishingService`.
-<2> standard metadata about the event, such as the user, the xref:rgcms.adoc#_rgcms_classes_mixins_HasTransactionId[`transactionId`], date/time etc
+<2> standard metadata about the event, such as the user, the xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins_HasTransactionId[`transactionId`], date/time etc
 <3> for published actions, will generally be an `EventPayloadForActionInvocation` (or subclass thereof); for published objects, will generally be an `EventPayloadForObjectChanged` (or subclass thereof)
 
 It's important to make sure that the publishing service implementation is able to handle the serialized form.  Strings are a good lowest common denominator, but in some cases a type-safe equivalent, such as a w3c DOM `Document` or JSON node might be passed instead.
@@ -66,15 +66,15 @@ There is no default implementation of this service provided by the core Apache I
 The (non-ASF) http://github.com/isisaddons/isis-module-publishing[Isis addons' publishing] module provides an
 implementation of this service (`RestfulObjectsSpecEventSerializer`) that serializes action invocations and published
 objects into a format based on the Restful Objects specification.  It also (as you might imagine) provides an
-implementation of the xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`].
+implementation of the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`].
 
-Assuming that an `AppManifest` is being used to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app])
+Assuming that an `AppManifest` is being used to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app])
 then this can be activated by updating the `pom.xml` and updating the `AppManifest#getModules()` method.
 
 
 
 == Related Services
 
-This service is intended (though not mandated) to be used by implementations of xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`].  The (non-ASF) http://github.com/isisaddons/isis-module-publishing[Isis addons' publishing] module does use it (though the (non-ASF)
+This service is intended (though not mandated) to be used by implementations of xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`].  The (non-ASF) http://github.com/isisaddons/isis-module-publishing[Isis addons' publishing] module does use it (though the (non-ASF)
 http://github.com/isisaddons/isis-module-publishmq[Isis addons' publishmq] module does not).
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_ExceptionRecognizer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_ExceptionRecognizer.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_ExceptionRecognizer.adoc
index 403a64e..85db100 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_ExceptionRecognizer.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_ExceptionRecognizer.adoc
@@ -97,7 +97,7 @@ If you want to recognize and handle additional exceptions (for example to captur
 == Registering the Services
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then the default
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then the default
 implementations provided by the framework (`DomainObjectContainerDefault` and
 `ExceptionRecognizerCompositeForJdoObjectStore`) will be registered.
 
@@ -115,5 +115,5 @@ isis.services=...,\
 Prior to 1.9.0, the `ExceptionRecognizerCompositeForJdoObjectStore` also required manual registration.
 ====
 
-If the JDO exception recognizers are not required (rather unlikely), then they can be disabled en-masse using the xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.services.ExceptionRecognizerCompositeForJdoObjectStore.disable`.
+If the JDO exception recognizers are not required (rather unlikely), then they can be disabled en-masse using the xref:../rgcfg/rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.services.ExceptionRecognizerCompositeForJdoObjectStore.disable`.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_FixtureScriptsSpecificationProvider.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_FixtureScriptsSpecificationProvider.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_FixtureScriptsSpecificationProvider.adoc
index dd9c6c9..1c7f7b4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_FixtureScriptsSpecificationProvider.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_FixtureScriptsSpecificationProvider.adoc
@@ -7,11 +7,11 @@
 
 
 The `FixtureScriptsSpecificationProvider` configures the
-xref:rgsvc.adoc#_rgsvc_api_FixtureScriptsDefault[`FixtureScriptsDefault`] domain service, providing the
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_FixtureScriptsDefault[`FixtureScriptsDefault`] domain service, providing the
 location to search for fixture scripts and other settings.
 
 The service is only used if the `FixtureScriptsDefault` service is instantiated as a fallback by the framework.  If
-the application provides its own subclass of xref:rgcms.adoc#_rgcms_classes_super_FixtureScripts[`FixtureScripts`]
+the application provides its own subclass of xref:../rgcms/rgcms.adoc#_rgcms_classes_super_FixtureScripts[`FixtureScripts`]
 superclass, then this provider service is not used.
 
 [TIP]
@@ -56,7 +56,7 @@ The class is immutable but it has a builder (obtained using `FixturescriptsSpeci
 
 == Implementation
 
-The xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] has a simple implementation of this service:
+The xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] has a simple implementation of this service:
 
 [source,java]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_GridLoaderService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_GridLoaderService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_GridLoaderService.adoc
index dc413bd..310a40c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_GridLoaderService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_GridLoaderService.adoc
@@ -22,9 +22,9 @@ public interface GridLoaderService {
 }
 ----
 <1> whether dynamic reloading of layouts is enabled.  The default implementation enables reloading for prototyping, disables in production
-<2> support metamodel invalidation/rebuilding of spec, eg as called by this xref:rgcms.adoc#__rgcms_classes_mixins_Object_rebuildMetamodel[Object mixin] action.
+<2> support metamodel invalidation/rebuilding of spec, eg as called by this xref:../rgcms/rgcms.adoc#__rgcms_classes_mixins_Object_rebuildMetamodel[Object mixin] action.
 <3> whether any persisted layout metadata (eg a `.layout.xml` file) exists for this domain class.
-<4> returns a new instance of a xref:rgcms.adoc#__rgcms_classes_layout_component[`Grid`] for the specified domain class, eg as loaded from a `layout.xml` file.  If none exists, will return null (and the calling xref:rgsvc.adoc#_rgsvc_spi_GridService[`GridService`] will use xref:rgsvc.adoc#_rgsvc_spi_GridSystemService[`GridSystemService`] to obtain a default grid for the domain class).
+<4> returns a new instance of a xref:../rgcms/rgcms.adoc#__rgcms_classes_layout_component[`Grid`] for the specified domain class, eg as loaded from a `layout.xml` file.  If none exists, will return null (and the calling xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_GridService[`GridService`] will use xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_GridSystemService[`GridSystemService`] to obtain a default grid for the domain class).
 
 
 
@@ -39,15 +39,15 @@ For example, the layout for a domain class `com.mycompany.myapp.Customer` would
 == Registering the Services
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]), then the
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]), then the
  default implementation of `GridLoaderService` is automatically registered and injected, and no further
  configuration is required.
 
 To use an alternative implementation, use
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
+xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+in the xref:../rgsvc/rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
 
 
 == Related Services
 
-This service is used by xref:rgsvc.adoc#_rgsvc_spi_GridService[`GridService`].
+This service is used by xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_GridService[`GridService`].

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_GridService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_GridService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_GridService.adoc
index 29eadd8..eb0360a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_GridService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_GridService.adoc
@@ -8,9 +8,9 @@
 
 The `GridService` provides the ability to load the XML layout (grid) for a domain class.   To do this it delegates:
 
-* to xref:rgsvc.adoc#_rgsvc_spi_GridLoaderService[`GridLoaderService`] to load a pre-existing layout for the domain class, if possible
+* to xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_GridLoaderService[`GridLoaderService`] to load a pre-existing layout for the domain class, if possible
 
-* to xref:rgsvc.adoc#_rgsvc_spi_GridSystemService[`GridSystemService`] to normalize the grid with respect to Apache
+* to xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_GridSystemService[`GridSystemService`] to normalize the grid with respect to Apache
 Isis' internal metamodel, in other words to ensure that all of the domain objects' properties, collections and actions are associated with regions of the grid.
 
 Once a grid has been loaded for a domain class, this is cached internally by Apache Isis' internal meta model (in the
@@ -34,15 +34,15 @@ public interface GridService {
 }
 ----
 <1> whether dynamic reloading of layouts is enabled.  The default implementation enables reloading for prototyping, disables in production
-<2> support metamodel invalidation/rebuilding of spec, eg as called by this xref:rgcms.adoc#__rgcms_classes_mixins_Object_rebuildMetamodel[Object mixin] action.
-<3> whether any persisted layout metadata (eg a `.layout.xml` file) exists for this domain class.  Just delegates to corresponding method in xref:rgsvc.adoc#_rgsvc_spi_GridLoaderService[`GridLoaderService`].
-<4> returns a new instance of a xref:rgcms.adoc#__rgcms_classes_layout_component[`Grid`] for the specified domain class, eg as loaded from a `layout.xml` file.  If none exists, will return null (and the calling xref:rgsvc.adoc#_rgsvc_spi_GridService[`GridService`] will use xref:rgsvc.adoc#_rgsvc_spi_GridSystemService[`GridSystemService`] to obtain a default grid for the domain class).
+<2> support metamodel invalidation/rebuilding of spec, eg as called by this xref:../rgcms/rgcms.adoc#__rgcms_classes_mixins_Object_rebuildMetamodel[Object mixin] action.
+<3> whether any persisted layout metadata (eg a `.layout.xml` file) exists for this domain class.  Just delegates to corresponding method in xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_GridLoaderService[`GridLoaderService`].
+<4> returns a new instance of a xref:../rgcms/rgcms.adoc#__rgcms_classes_layout_component[`Grid`] for the specified domain class, eg as loaded from a `layout.xml` file.  If none exists, will return null (and the calling xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_GridService[`GridService`] will use xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_GridSystemService[`GridSystemService`] to obtain a default grid for the domain class).
 <5> returns a default grid, eg two columns in ratio 4:8.  Used when no existing grid layout exists for a domain class.
-<6> validates and normalizes a grid, modifying the grid so that all of the domain object's members (properties, collections, actions) are bound to regions of the grid.  This is done using existing metadata, most notably that of the xref:rgant.adoc#_rgant-MemberOrder[`@MemberOrder`] annotation.  Such a grid, if persisted as the layout XML file for the domain class, allows the `@MemberOrder` annotation to be removed from the source code of the domain class (but other annotations must be retained).
-<7> Takes a normalized grid and enriches it with additional metadata (taken from Apache Isis' internal metadata) that can be represented in the layout XML.  Such a grid, if persisted as the layout XML file for the domain class, allows all layout annotations (xref:rgant.adoc#_rgant-ActionLayout[`@ActionLayout`], xref:rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`] and xref:rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`]) to be removed from the source code of the domain class.
-<8> Takes a normalized grid and strips out removes all members, leaving only the grid structure.  Such a grid, if persisted as the layout XML file for the domain class, requires that the xref:rgant.adoc#_rgant-MemberOrder[`@MemberOrder`] annotation is retained in the source code of said class in order to bind members to the regions of the grid.
+<6> validates and normalizes a grid, modifying the grid so that all of the domain object's members (properties, collections, actions) are bound to regions of the grid.  This is done using existing metadata, most notably that of the xref:../rgant/rgant.adoc#_rgant-MemberOrder[`@MemberOrder`] annotation.  Such a grid, if persisted as the layout XML file for the domain class, allows the `@MemberOrder` annotation to be removed from the source code of the domain class (but other annotations must be retained).
+<7> Takes a normalized grid and enriches it with additional metadata (taken from Apache Isis' internal metadata) that can be represented in the layout XML.  Such a grid, if persisted as the layout XML file for the domain class, allows all layout annotations (xref:../rgant/rgant.adoc#_rgant-ActionLayout[`@ActionLayout`], xref:../rgant/rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`] and xref:../rgant/rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`]) to be removed from the source code of the domain class.
+<8> Takes a normalized grid and strips out removes all members, leaving only the grid structure.  Such a grid, if persisted as the layout XML file for the domain class, requires that the xref:../rgant/rgant.adoc#_rgant-MemberOrder[`@MemberOrder`] annotation is retained in the source code of said class in order to bind members to the regions of the grid.
 
-The first four methods just delegate to the corresponding methods in xref:rgsvc.adoc#_rgsvc_spi_GridSystemService[`GridSystemService`], while the last four delegate to the  corresponding method in xref:rgsvc.adoc#_rgsvc_spi_GridSystemService[`GridSystemService`].  The service inspects the ``Grid``'s concrete class to determine which actual `GridSystemService` instance to delegate to.
+The first four methods just delegate to the corresponding methods in xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_GridSystemService[`GridSystemService`], while the last four delegate to the  corresponding method in xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_GridSystemService[`GridSystemService`].  The service inspects the ``Grid``'s concrete class to determine which actual `GridSystemService` instance to delegate to.
 
 
 == Implementation
@@ -53,20 +53,20 @@ The framework provides a default implementation of this service, namely `GridSer
 == Registering the Services
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]), then the
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]), then the
  default implementation of `GridLoaderService` is automatically registered and injected, and no further
  configuration is required.
 
 To use an alternative implementation, use
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
+xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+in the xref:../rgsvc/rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
 That said, there should be little reason to use a different implementation; if behaviour does need to be changed, it would also be possible to replace the implementation of either the `GridLoaderService` or the `GridSystemService`.
 
 
 
 == Related Services
 
-This service calls xref:rgsvc.adoc#_rgsvc_spi_GridLoaderService[`GridLoaderService`] and xref:rgsvc.adoc#_rgsvc_spi_GridSystemService[`GridSystemService`].
+This service calls xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_GridLoaderService[`GridLoaderService`] and xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_GridSystemService[`GridSystemService`].
 
-This service is called by xref:rgsvc.adoc#_rgsvc_api_LayoutService[`LayoutService`], exposed in the UI through `LayoutServiceMenu` (to download the layout XML as a zip file for all domain objects) and the xref:rgcms.adoc#_rgcms_classes_mixins_Object[`downloadLayoutXml()`] mixin (to download the layout XML for a single domain
+This service is called by xref:../rgsvc/rgsvc.adoc#_rgsvc_api_LayoutService[`LayoutService`], exposed in the UI through `LayoutServiceMenu` (to download the layout XML as a zip file for all domain objects) and the xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins_Object[`downloadLayoutXml()`] mixin (to download the layout XML for a single domain
 object).

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_GridSystemService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_GridSystemService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_GridSystemService.adoc
index a4e09d8..d610cee 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_GridSystemService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_GridSystemService.adoc
@@ -18,7 +18,7 @@ The framework provides a single such grid implementation, namely for Bootstrap3.
 Unlike most other domain services, the framework will check _all_ available implementations of `GridSystemService` to
 obtain available grid systems, rather than merely the first implementation found; in other words it uses the
 chain-of-responsibility pattern.  Services are called in the order defined by
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`]).
+xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`]).
 
 Note though that each concrete implementation must also provide corresponding Wicket viewer components capable of
 interpreting the grid layout.
@@ -42,14 +42,14 @@ public interface GridSystemService<G extends Grid> {
 }
 ----
 <1> The concrete subclass of `Grid` supported by this implementation. As noted in the introduction, there can be multiple implementations of this service,  but there can only be one implementation per concrete subclass.  As is normal practice,
-the service with the lowest xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] takes precedence.
+the service with the lowest xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] takes precedence.
 <2> the target namespace for this grid system.  This is used when generating the XML.  The Bootstrap3 grid system provided by the framework returns the value `http://isis.apache.org/applib/layout/grid/bootstrap3`.
 <3> the schema location for the XSD.  The Bootstrap3 grid system provided by the framework returns the value `http://isis.apache.org/applib/layout/grid/bootstrap3/bootstrap3.xsd`.
 <4> a default grid, eg two columns in ratio 4:8.  Used when no existing grid layout exists for a domain class.
-<5> Validates and normalizes a grid, modifying the grid so that all of the domain object's members (properties, collections, actions) are bound to regions of the grid.  This is done using existing metadata, most notably that of the xref:rgant.adoc#_rgant-MemberOrder[`@MemberOrder`] annotation.  Such a grid, if persisted as the layout XML file for the domain class, allows the
+<5> Validates and normalizes a grid, modifying the grid so that all of the domain object's members (properties, collections, actions) are bound to regions of the grid.  This is done using existing metadata, most notably that of the xref:../rgant/rgant.adoc#_rgant-MemberOrder[`@MemberOrder`] annotation.  Such a grid, if persisted as the layout XML file for the domain class, allows the
  `@MemberOrder` annotation to be removed from the source code of the domain class (but other annotations must be retained).
-<6> Takes a normalized grid and enriches it with additional metadata (taken from Apache Isis' internal metadata) that can be represented in the layout XML.  Such a grid, if persisted as the layout XML file for the domain class, allows all layout annotations (xref:rgant.adoc#_rgant-ActionLayout[`@ActionLayout`], xref:rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`] and xref:rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`]) to be removed from the source code of the domain class.
-<7> Takes a normalized grid and strips out removes all members, leaving only the grid structure.  Such a grid, if persisted as the layout XML file for the domain class, requires that the xref:rgant.adoc#_rgant-MemberOrder[`@MemberOrder`] annotation is retained in the source code of said class in order to bind members to the regions of the grid.
+<6> Takes a normalized grid and enriches it with additional metadata (taken from Apache Isis' internal metadata) that can be represented in the layout XML.  Such a grid, if persisted as the layout XML file for the domain class, allows all layout annotations (xref:../rgant/rgant.adoc#_rgant-ActionLayout[`@ActionLayout`], xref:../rgant/rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`] and xref:../rgant/rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`]) to be removed from the source code of the domain class.
+<7> Takes a normalized grid and strips out removes all members, leaving only the grid structure.  Such a grid, if persisted as the layout XML file for the domain class, requires that the xref:../rgant/rgant.adoc#_rgant-MemberOrder[`@MemberOrder`] annotation is retained in the source code of said class in order to bind members to the regions of the grid.
 
 
 == Implementation
@@ -61,15 +61,15 @@ also provides xref:ugvw.adoc[Wicket viewer] components that are capable of inter
 == Registering the Services
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]), then the
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]), then the
  Bootstrap3 default implementation of `GridSystemService` is automatically registered and injected, and no further
  configuration is required.
 
 To use an alternative implementation, use
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
+xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+in the xref:../rgsvc/rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
 
 
 == Related Services
 
-This service is used by xref:rgsvc.adoc#_rgsvc_spi_GridService[`GridService`].
+This service is used by xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_GridService[`GridService`].

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_HintStore.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_HintStore.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_HintStore.adoc
index c8af9d9..34bfcca 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_HintStore.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_HintStore.adoc
@@ -30,7 +30,7 @@ public interface HintStore {
 }
 ----
 <1> obtain a hint (eg which tab to open) for a particular object.  Object identity is represented by `Bookmark`, as
-per the xref:rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`], so that alternative implementations can easily serialize this state to a string.
+per the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`], so that alternative implementations can easily serialize this state to a string.
 <2> set the state of a hint.  (The value of) all hints are represented as strings.
 <3> remove a single hint for an object;
 <4> remove all hints
@@ -48,17 +48,17 @@ The core framework provides a default implementation of this service (`org.apach
 == Registering the Service
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
 implementation of `HintStore` service is automatically registered and injected (it is annotated with
 `@DomainService`) so no further configuration is required.
 
 To use an alternative implementation, use
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
+xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+in the xref:../rgsvc/rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
 
 
 == Related Services
 
-The xref:ugvw.adoc[Wicket viewer] exposes the xref:rgcms.adoc#__rgcms_classes_mixins_Object_clearHints["clear hints"]
+The xref:ugvw.adoc[Wicket viewer] exposes the xref:../rgcms/rgcms.adoc#__rgcms_classes_mixins_Object_clearHints["clear hints"]
 mixin action that is for use by end-users of the application to clear any UI hints that have accumulated for a
 domain object.

http://git-wip-us.apache.org/repos/asf/isis/blob/252c2f8e/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_LocaleProvider.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_LocaleProvider.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_LocaleProvider.adoc
index a0155a1..a31b079 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_LocaleProvider.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_LocaleProvider.adoc
@@ -6,7 +6,7 @@
 
 
 
-The `LocaleProvider` service is one of the services that work together to implement Apache Isis' support for i18n, being used by Isis' default implementation of xref:rgsvc.adoc#_rgsvc_spi_TranslationService[`TranslationService`].
+The `LocaleProvider` service is one of the services that work together to implement Apache Isis' support for i18n, being used by Isis' default implementation of xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_TranslationService[`TranslationService`].
 
 The role of the service itself is simply to return the `Locale` of the current user.
 
@@ -30,7 +30,7 @@ public interface LocaleProvider {
 }
 ----
 
-This is notionally request-scoped, returning the `Locale` of the current user; _not_ that of the server.  (Note that the implementation is not required to actually be xref:rgant.adoc#_rgant-RequestScoped[`@RequestScoped`], however).
+This is notionally request-scoped, returning the `Locale` of the current user; _not_ that of the server.  (Note that the implementation is not required to actually be xref:../rgant/rgant.adoc#_rgant-RequestScoped[`@RequestScoped`], however).
 
 
 
@@ -50,20 +50,20 @@ Currently there is no equivalent implementation for the xref:ugvro.adoc#[Restful
 == Registering the Services
 
 Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]), __and__ that the
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]), __and__ that the
 xref:ugvw.adoc#[Wicket viewer] is being used, then an implementation of `LocaleProvider` is
 automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
 
 To use an alternative implementation, use
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
+xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+in the xref:../rgsvc/rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
 
 
 
 
 == Related Services
 
-This service works in conjunction with xref:rgsvc.adoc#_rgsvc_spi_TranslationService[`TranslationService`] and xref:rgsvc.adoc#_rgsvc_spi_TranslationsResolver[`TranslationsResolver`] in order to provide i18n support.
+This service works in conjunction with xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_TranslationService[`TranslationService`] and xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_TranslationsResolver[`TranslationsResolver`] in order to provide i18n support.
 
 
 

[42/58] [abbrv] isis git commit: ISIS-1521: adds hints-n-tips sections for most of the user guides, and distributes out tips from dg.adoc as appropriate

[da...@apache.org]

ISIS-1521: adds hints-n-tips sections for most of the user guides, and distributes out tips from dg.adoc as appropriate


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/fcf368f0
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/fcf368f0
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/fcf368f0

Branch: refs/heads/wip
Commit: fcf368f0c94cb56f3783d5033477b5f9742379bb
Parents: 4807f4c
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Fri Apr 14 16:13:05 2017 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Thu Apr 20 09:09:30 2017 +0100

----------------------------------------------------------------------
 .../asciidoc/guides/dg/_dg_hints-and-tips.adoc  | 24 ++++--
 ...ips_how-to-handle-void-and-null-results.adoc | 79 -----------------
 ...nd-tips_how-to-implement-a-spellchecker.adoc | 29 -------
 ...ts-and-tips_i18n-label-in-wicket-viewer.adoc | 26 ------
 .../dg/_dg_hints-and-tips_per-user-themes.adoc  | 91 --------------------
 ...g_hints-and-tips_restful-image-property.adoc | 25 ------
 ...tips_subtype-entity-not-fully-populated.adoc | 60 -------------
 .../rgsvc/_rgsvc_api_RepositoryService.adoc     |  2 +-
 .../guides/ugbtb/_ugbtb_hints-and-tips.adoc     | 27 ++++++
 ...ips_how-to-handle-void-and-null-results.adoc | 79 +++++++++++++++++
 ...nd-tips_how-to-implement-a-spellchecker.adoc | 29 +++++++
 .../src/main/asciidoc/guides/ugbtb/ugbtb.adoc   |  1 +
 .../guides/ugodn/_ugodn_hints-and-tips.adoc     | 27 ++++++
 .../ugodn/_ugodn_hints-and-tips_java8.adoc      | 29 +++++++
 ...nts-and-tips_overriding-jdo-annotations.adoc | 64 ++++++++++++++
 ...tips_subtype-entity-not-fully-populated.adoc | 60 +++++++++++++
 .../asciidoc/guides/ugodn/_ugodn_java8.adoc     | 29 -------
 .../_ugodn_overriding-jdo-annotations.adoc      | 64 --------------
 .../src/main/asciidoc/guides/ugodn/ugodn.adoc   |  3 +-
 .../_ugsec_configuring-isis-to-use-bypass.adoc  | 23 -----
 .../guides/ugsec/_ugsec_hints-and-tips.adoc     | 28 ++++++
 ...and-tips_configuring-isis-to-use-bypass.adoc | 23 +++++
 .../src/main/asciidoc/guides/ugsec/ugsec.adoc   |  3 +-
 .../guides/ugvro/_ugvro_hints-and-tips.adoc     | 87 +++----------------
 .../_ugvro_hints-and-tips_angular-tips.adoc     | 69 +++++++++++++++
 .../_ugvro_hints-and-tips_pretty-printing.adoc  | 13 +++
 ...o_hints-and-tips_restful-image-property.adoc | 25 ++++++
 ...ro_hints-and-tips_using-chrome-devtools.adoc |  9 ++
 .../_ugvw_extending_custom-bootstrap-theme.adoc |  2 +-
 .../guides/ugvw/_ugvw_hints-and-tips.adoc       | 31 +++++++
 ...ts-and-tips_i18n-label-in-wicket-viewer.adoc | 26 ++++++
 .../_ugvw_hints-and-tips_per-user-themes.adoc   | 91 ++++++++++++++++++++
 .../src/main/asciidoc/guides/ugvw/ugvw.adoc     |  2 +-
 33 files changed, 666 insertions(+), 514 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc
index 78cfee4..26253ea 100644
--- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc
@@ -6,18 +6,24 @@
 :toc: right
 
 
+This chapter provides some solutions for problems we've encountered ourselves or have been raised on the Apache Isis mailing lists.
 
-This chapter has FAQs (with solutions) for problems we've encountered ourselves or have been raised on the
-Apache Isis mailing lists.
+See also hints-n-tips chapters in the:
+
+* the xref:../dg/dg.adoc#_ugvw_hints-and-tips[Developers'] guide (this chapter)
+
+* the xref:../ugvw/ugvw.adoc#_ugvw_hints-and-tips[Wicket viewer] guide
+
+* the xref:../ugvro/ugvro.adoc#_ugvro_hints-and-tips[Restful Objects viewer] guide
+
+* the xref:../ugvro/ugodn.adoc#_ugodn_hints-and-tips[Datanucleus ObjectStore] guide
+
+* the xref:../ugsec/ugsec.adoc#_ugsec_hints-and-tips[Security] guide
+
+* the xref:../ugbtb/ugbtb.adoc#_ugbtb_hints-and-tips[Beyond the Basics] guide.
 
-See also xref:../ugvro/ugvro.adoc#_ugvro_hints-and-tips[Restful Objects hints-n-tips].
 
 include::_dg_hints-and-tips_enabling-logging.adoc[leveloffset=+1]
-include::_dg_hints-and-tips_subtype-entity-not-fully-populated.adoc[leveloffset=+1]
-include::_dg_hints-and-tips_restful-image-property.adoc[leveloffset=+1]
 include::_dg_hints-and-tips_enhance-only.adoc[leveloffset=+1]
-include::_dg_hints-and-tips_per-user-themes.adoc[leveloffset=+1]
-include::_dg_hints-and-tips_i18n-label-in-wicket-viewer.adoc[leveloffset=+1]
-include::_dg_hints-and-tips_how-to-handle-void-and-null-results.adoc[leveloffset=+1]
-include::_dg_hints-and-tips_how-to-implement-a-spellchecker.adoc[leveloffset=+1]
 include::_dg_hints-and-tips_how-run-fixtures-on-app-startup.adoc[leveloffset=+1]
+

http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-to-handle-void-and-null-results.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-to-handle-void-and-null-results.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-to-handle-void-and-null-results.adoc
deleted file mode 100644
index 373b1e6..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-to-handle-void-and-null-results.adoc
+++ /dev/null
@@ -1,79 +0,0 @@
-[[_dg_hints-and-tips_how-to-handle-void-and-null-results]]
-= How to handle void/null results
-: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/
-
-
-
-From this link:http://isis.markmail.org/thread/yf7qdeiu3vrvk2ei[thread] on the Apache Isis users mailing list:
-
-* _When using a `void` action, let\u2019s say a remove action, the user is redirected to a
-page "no results".
-When clicking the back button in the browser the user sees "Object not found" (since you\u2019ve just deleted this object)._
-
-* _You can return a list for example to prevent the user from being redirect to a
-  "No results" page, but I think it\u2019s not the responsibility of the controllers in
-  the domain model._
-
-* _A solution could be that wicket viewer goes back one page when
-  encountering a deleted object.
-And refresh the current page when receiving a null response or invoking a void action.
-But how to implement this?_
-
-One way to implement this idea is to provide a custom implementation of the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_RoutingService[`RoutingService`] SPI domain service.
-The default implementation will either return the current object (if not null), else the home page (as defined by xref:../rgant/rgant.adoc#_rgant-HomePage[`@HomePage`]) if one exists.
-
-The following custom implementation refines this to use the breadcrumbs (available in the Wicket viewer) to return the first non-deleted domain object found in the list of breadcrumbs:
-
-[source,java]
-----
-@DomainService(nature = NatureOfService.DOMAIN)
-@DomainServiceLayout(menuOrder = "1")                                           // <1>
-public class RoutingServiceUsingBreadcrumbs extends RoutingServiceDefault {
-    @Override
-    public Object route(final Object original) {
-        if(original != null) {                                                  // <2>
-            return original;
-        }
-        container.flush();                                                      // <3>
-
-        final BreadcrumbModelProvider wicketSession =                           // <4>
-            (BreadcrumbModelProvider) AuthenticatedWebSession.get();
-        final BreadcrumbModel breadcrumbModel =
-            wicketSession.getBreadcrumbModel();
-        final List<EntityModel> breadcrumbs = breadcrumbModel.getList();
-
-        final Optional<Object> firstViewModelOrNonDeletedPojoIfAny =
-                breadcrumbs.stream()                                            // <5>
-                .filter(entityModel -> entityModel != null)
-                .map(EntityModel::getObject)                                    // <6>
-                .filter(objectAdapter -> objectAdapter != null)
-                .map(ObjectAdapter::getObject)                                  // <7>
-                .filter(pojo -> !(pojo instanceof Persistable) ||
-                                !((Persistable)pojo).dnIsDeleted())             // <8>
-                .findFirst();
-
-        return firstViewModelOrNonDeletedPojoIfAny.orElse(homePage());          // <9>
-    }
-    private Object homePage() {
-        return homePageProviderService.homePage();
-    }
-    @Inject
-    HomePageProviderService homePageProviderService;
-    @Inject
-    DomainObjectContainer container;
-}
-----
-<1> override the default imlpementation
-<2> if a non-null object was returned, then return this
-<3> ensure that any persisted objects have been deleted.
-<4> reach inside the Wicket viewer's internals to obtain the list of breadcrumbs.
-<5> loop over all breadcrumbs
-<6> unwrap the Wicket viewer's serializable representation of each domain object (`EntityModel`) to the Isis runtime's
-representation (`ObjectAdapter`)
-<7> unwrap the Isis runtime's representation of each domain object (`ObjectAdapter`) to the domain object pojo itself
-<8> if object is persistable (not a view model) then make sure it is not deleted
-<9> return the first object if any, otherwise the home page object (if any).
-
-Note that the above implementation uses Java 8, so if you are using Java 7 then you'll need to backport accordingly.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-to-implement-a-spellchecker.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-to-implement-a-spellchecker.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-to-implement-a-spellchecker.adoc
deleted file mode 100644
index d165a65..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-to-implement-a-spellchecker.adoc
+++ /dev/null
@@ -1,29 +0,0 @@
-[[_dg_hints-and-tips_how-to-implement-a-spellchecker]]
-= How to implement a spellchecker?
-: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/
-
-
-
-From this link:http://isis.markmail.org/thread/dduarjscrbnodfsi[thread] on the Apache Isis users mailing list:
-
-* _What is the easiest way to add a spell checker to the text written in a field in
-   a domain object, for instance to check English syntax?_
-
-One way to implement is to use the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[event bus]:
-
-* Set up a xref:rgcsm.adoc#_rgcsm_classes_domainevent[domain event] xref:rgcsm.adoc#_rgcsm_classes_super_AbstractSubscriber[subscriber] that can veto the changes.
-
-* if the change is made through an action, you can use xref:../rgant/rgant.adoc#_rgant-Action_domainEvent[`@Action#domainEvent()`].
-
-if if the change is made through an edit, you can use xref:../rgant/rgant.adoc#_rgant-Property_domainEvent[`@Property#domainEvent()`].
-
-You'll need some way to know which fields should be spell checked.  Two ways spring to mind:
-
-* either look at the domain event's identifier
-
-* or subclass the domain event (recommended anyway) and have those subclass events implement some sort of marker interface, eg a `SpellCheckEvent`.
-
-And you'll (obviously) also need some sort of spell checker implementation to call.
-

http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_i18n-label-in-wicket-viewer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_i18n-label-in-wicket-viewer.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_i18n-label-in-wicket-viewer.adoc
deleted file mode 100644
index d4d16e0..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_i18n-label-in-wicket-viewer.adoc
+++ /dev/null
@@ -1,26 +0,0 @@
-[[_dg_hints-and-tips_i18n-label-in-wicket-viewer]]
-= How i18n the Wicket viewer?
-: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/
-
-
-
-From link:http://isis.markmail.org/thread/ctppmtcbsf4iskzi[this thread] on the Apache Isis users mailing list:
-
-* _I am trying to internationalize the label descriptions of form actions, eg those in `ActionParametersFormPanel`.
-Referencing those via their message id inside a .po file didn't work either.
-Can this be done?_
-
-
-The above FAQ was raised against `1.10.0`.  As of `1.11.0` (due to link:https://issues.apache.org/jira/browse/ISIS-1093[ISIS-1093]) it _is_ now possible to internationalize both the Wicket viewer's labels as well as the regular translations of the domain object metadata using the `.po` translation files as supported by the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_TranslationService[`TranslationService`].
-
-Full details of the ``msgId``s that must be added to the `translations.po` file can be found in xref:guides/ugbtb.adoc#__ugbtb_i18n_wicket-viewer[i18n] section of the xref:../ugbtb/ugbtb.adoc#[beyond the basics] guide.
-
-In prior releases (`1.10.0` and earlier) it was necessary to use link:https://ci.apache.org/projects/wicket/guide/6.x/guide/i18n.html#i18n_3[Wicket's internationalization support], namely resource bundles.  This is still supported (as a fallback):
-
-* create a directory structure inside the webapp resource folder following that pattern `org.apache.isis.viewer.wicket.ui.components.actions`
-
-* Inside there create an equivalent `ActionParametersFormPanel_xx_XX.properties` or `ActionParametersFormPanel_xx.properties` file for the various locales that you want to support (eg `ActionParametersFormPanel_en_UK.properties`, `ActionParametersFormPanel_en_US.properties`, `ActionParametersFormPanel_de.properties` and so on).
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_per-user-themes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_per-user-themes.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_per-user-themes.adoc
deleted file mode 100644
index 10a89f1..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_per-user-themes.adoc
+++ /dev/null
@@ -1,91 +0,0 @@
-[[_dg_hints-and-tips_per-user-themes]]
-= Per-user Themes
-: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/
-
-
-From link:http://isis.markmail.org/thread/kb4442niwwbnghey[this thread] on the Apache Isis users mailing list:
-
-* _Is it possible to have each of our resellers (using our Isis application) use there own theme/branding with their own logo and colors?
-Would this also be possible for the login page, possibly depending on the used host name?_
-
-
-Yes, you can do this, by installing a custom implementation of the Wicket Bootstrap's `ActiveThemeProvider`.
-
-The http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] (non-ASF) actually link:https://github.com/isisaddons/isis-app-todoapp/tree/61b8114a8e01dbb3c380b31cf09eaed456407570[does this], storing the info via the http://github.com/isisaddons/isis-module-settings[Isis addons' settings module] settings modules:
-
-
-[source,java]
-.IActiveThemeProvider implementation
-----
-public class UserSettingsThemeProvider implements ActiveThemeProvider {
-    ...
-    @Override
-    public ITheme getActiveTheme() {
-        if(IsisContext.getSpecificationLoader().isInitialized()) {
-            final String themeName = IsisContext.doInSession(new Callable<String>() {
-                @Override
-                public String call() throws Exception {
-                    final UserSettingsService userSettingsService =
-                        lookupService(UserSettingsService.class);
-                    final UserSetting activeTheme = userSettingsService.find(
-                            IsisContext.getAuthenticationSession().getUserName(),
-                            ACTIVE_THEME);
-                    return activeTheme != null ? activeTheme.valueAsString() : null;
-                }
-            });
-            return themeFor(themeName);
-        }
-        return new SessionThemeProvider().getActiveTheme();
-    }
-    @Override
-    public void setActiveTheme(final String themeName) {
-        IsisContext.doInSession(new Runnable() {
-            @Override
-            public void run() {
-                final String currentUsrName =
-                    IsisContext.getAuthenticationSession().getUserName();
-                final UserSettingsServiceRW userSettingsService =
-                        lookupService(UserSettingsServiceRW.class);
-                final UserSettingJdo activeTheme =
-                        (UserSettingJdo) userSettingsService.find(
-                                                currentUsrName, ACTIVE_THEME);
-                if(activeTheme != null) {
-                    activeTheme.updateAsString(themeName);
-                } else {
-                    userSettingsService.newString(
-                        currentUsrName, ACTIVE_THEME, "Active Bootstrap theme for user", themeName);
-                }
-            }
-        });
-    }
-    private ITheme themeFor(final String themeName) {
-        final ThemeProvider themeProvider = settings.getThemeProvider();
-        if(themeName != null) {
-            for (final ITheme theme : themeProvider.available()) {
-                if (themeName.equals(theme.name()))
-                    return theme;
-            }
-        }
-        return themeProvider.defaultTheme();
-    }
-    ...
-}
-----
-
-and
-
-[source,java]
-.Using the ActiveThemeProvider
-----
-@Override
-protected void init() {
-    super.init();
-
-    final IBootstrapSettings settings = Bootstrap.getSettings();
-    settings.setThemeProvider(new BootswatchThemeProvider(BootswatchTheme.Flatly));
-
-    settings.setActiveThemeProvider(new UserSettingsThemeProvider(settings));
-}
-----

http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_restful-image-property.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_restful-image-property.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_restful-image-property.adoc
deleted file mode 100644
index a01564d..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_restful-image-property.adoc
+++ /dev/null
@@ -1,25 +0,0 @@
-[[_dg_hints-and-tips_restful-image-property]]
-= How parse images in RO viewer?
-: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/
-
-
-From this link:http://markmail.org/message/4kcu7sml4ufdsah3[thread] on the Apache Isis users mailing list:
-
-* _I am trying to display an image in a JavaScript client app, the image comes from
-   an Isis RO web service as a string, but it won't show.
-Is there something I should do to change the message?_
-
-
-The RO viewer returns the image as a string, in the form:
-
-    "Tacos.jpg:image/jpeg:/9j//4AAQSkZJRgABAQEAlgCWAAD/  ...."
-
-This is in the form:
-
-    (filename):(mime type):(binary data in base64)
-
-This is basically the xref:../rgcms/rgcms.adoc#_rgcms_classes_value-types_Blob[`Blob`] value type, in string form.
-
-To use, split the parts then format the mime type and base64 data correctly before using as source in an `<img>` tag.

http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_subtype-entity-not-fully-populated.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_subtype-entity-not-fully-populated.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_subtype-entity-not-fully-populated.adoc
deleted file mode 100644
index d5f5965..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_subtype-entity-not-fully-populated.adoc
+++ /dev/null
@@ -1,60 +0,0 @@
-[[_dg_hints-and-tips_subtype-entity-not-fully-populated]]
-= Subtype not fully populated
-: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/
-
-
-Taken from link:http://markmail.org/message/ovgai56uqgfgnrx7[this thread] on the Apache Isis users mailing list...
-
-
-If it seems that Apache Isis (or rather DataNucleus) isn't fully populating domain entities (ie leaving some properties as `null`), then check that your actions are not accessing the fields directly.
-Use getters instead.
-
-
-[WARNING]
-====
-Properties of domain entities should always be accessed using getters.
-The only code that should access to fields should be the getters themselves.
-====
-
-Why so?
-Because DataNucleus will potentially lazy load some properties, but to do this it needs to know that the field is being requested.
-This is the purpose of the enhancement phase: the bytecode of the original getter method is actually wrapped in code that does the lazy loading checking.
-But hitting the field directly means that the lazy loading code does not run.
-
-This error can be subtle: sometimes "incorrect" code that accesses the fields will seem to work.
-But that will be because the field has been populated already, for whatever reason.
-
-One case where you will find the issue highlighted is for subtype tables that have been mapped using an inheritance strategy of `NEW_TABLE`, eg:
-
-[source,java]
-----
-@javax.jdo.annotations.PersistenceCapable
-@javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.NEW_TABLE)
-public class SupertypeEntity {
-    ...
-}
-----
-
-and then:
-
-[source,java]
-----
-@javax.jdo.annotations.PersistenceCapable
-@javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.NEW_TABLE)
-public class SubtypeEntity extends SupertypeEntity {
-    ...
-}
-----
-
-This will generate two tables in the database, with the primary key of the supertype table propagated as a foreign key (also primary key) of the subtype table (sometimes called "table per type" strategy).
-This means that DataNucleus might retrieve data from only the supertype table, and the lazily load the subtype fields only as required.
-This is preferable to doing a left outer join from the super- to the subtype tables to retrieve data that might not be needed.
-
-On the other hand, if the `SUPERCLASS_TABLE` strategy (aka "table per hierarchy" or roll-up) or the `SUBCLASS_TABLE` strategy (roll-down) was used, then the problem is less likely to occur because DataNucleus would obtain all the data for any given instance from a single table.
-
-Final note: references to other objects (either scalar references or in collections) in particular require that getters rather than fields to be used to obtain them: it's hopefully obvious that DataNucleus (like all ORMs) should not and will not resolve such references (otherwise, where to stop... and the whole database would be loaded into memory).
-
-In summary, there's just one rule: *always use the getters, never the fields*.
-

http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_RepositoryService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_RepositoryService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_RepositoryService.adoc
index 362cb88..1429962 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_RepositoryService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_RepositoryService.adoc
@@ -136,7 +136,7 @@ public abstract class Warehouse extends SalesVIPEntity<Marketplace> {
 <2> Needed for updating the managed properties and collections.
 <3> injected services and other methods ommited
 
-On the \u201caddExcludedProduct()\u201d action, if the user didn\u2019t flush, the following test would fail because the managed
+On the \u201caddExcludedProduct()\u201d action, if the user didn't flush, the following test would fail because the managed
 collection would not containing the given product:
 
 [source,java]

http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips.adoc
new file mode 100644
index 0000000..589802f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips.adoc
@@ -0,0 +1,27 @@
+[[_ugbtb_hints-and-tips]]
+= Hints and Tips
+: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/
+:toc: right
+
+
+This chapter provides some solutions for problems we've encountered ourselves or have been raised on the Apache Isis mailing lists.
+
+See also hints-n-tips chapters in the:
+
+* the xref:../dg/dg.adoc#_ugvw_hints-and-tips[Developers'] guide
+
+* the xref:../ugvw/ugvw.adoc#_ugvw_hints-and-tips[Wicket viewer] guide
+
+* the xref:../ugvro/ugvro.adoc#_ugvro_hints-and-tips[Restful Objects viewer] guide
+
+* the xref:../ugvro/ugodn.adoc#_ugodn_hints-and-tips[Datanucleus ObjectStore] guide
+
+* the xref:../ugsec/ugsec.adoc#_ugsec_hints-and-tips[Security] guide
+
+* the xref:../ugbtb/ugbtb.adoc#_ugbtb_hints-and-tips[Beyond the Basics] guide (this chapter).
+
+
+include::_ugbtb_hints-and-tips_how-to-handle-void-and-null-results.adoc[leveloffset=+1]
+include::_ugbtb_hints-and-tips_how-to-implement-a-spellchecker.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_how-to-handle-void-and-null-results.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_how-to-handle-void-and-null-results.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_how-to-handle-void-and-null-results.adoc
new file mode 100644
index 0000000..c870a51
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_how-to-handle-void-and-null-results.adoc
@@ -0,0 +1,79 @@
+[[_ugbtb_hints-and-tips_how-to-handle-void-and-null-results]]
+= How to handle void/null results
+: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/
+
+
+
+From this link:http://isis.markmail.org/thread/yf7qdeiu3vrvk2ei[thread] on the Apache Isis users mailing list:
+
+* _When using a `void` action, let's say a remove action, the user is redirected to a
+page "no results".
+When clicking the back button in the browser the user sees "Object not found" (since you've just deleted this object)._
+
+* _You can return a list for example to prevent the user from being redirect to a
+  "No results" page, but I think it's not the responsibility of the controllers in
+  the domain model._
+
+* _A solution could be that wicket viewer goes back one page when
+  encountering a deleted object.
+And refresh the current page when receiving a null response or invoking a void action.
+But how to implement this?_
+
+One way to implement this idea is to provide a custom implementation of the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_RoutingService[`RoutingService`] SPI domain service.
+The default implementation will either return the current object (if not null), else the home page (as defined by xref:../rgant/rgant.adoc#_rgant-HomePage[`@HomePage`]) if one exists.
+
+The following custom implementation refines this to use the breadcrumbs (available in the Wicket viewer) to return the first non-deleted domain object found in the list of breadcrumbs:
+
+[source,java]
+----
+@DomainService(nature = NatureOfService.DOMAIN)
+@DomainServiceLayout(menuOrder = "1")                                           // <1>
+public class RoutingServiceUsingBreadcrumbs extends RoutingServiceDefault {
+    @Override
+    public Object route(final Object original) {
+        if(original != null) {                                                  // <2>
+            return original;
+        }
+        container.flush();                                                      // <3>
+
+        final BreadcrumbModelProvider wicketSession =                           // <4>
+            (BreadcrumbModelProvider) AuthenticatedWebSession.get();
+        final BreadcrumbModel breadcrumbModel =
+            wicketSession.getBreadcrumbModel();
+        final List<EntityModel> breadcrumbs = breadcrumbModel.getList();
+
+        final Optional<Object> firstViewModelOrNonDeletedPojoIfAny =
+                breadcrumbs.stream()                                            // <5>
+                .filter(entityModel -> entityModel != null)
+                .map(EntityModel::getObject)                                    // <6>
+                .filter(objectAdapter -> objectAdapter != null)
+                .map(ObjectAdapter::getObject)                                  // <7>
+                .filter(pojo -> !(pojo instanceof Persistable) ||
+                                !((Persistable)pojo).dnIsDeleted())             // <8>
+                .findFirst();
+
+        return firstViewModelOrNonDeletedPojoIfAny.orElse(homePage());          // <9>
+    }
+    private Object homePage() {
+        return homePageProviderService.homePage();
+    }
+    @Inject
+    HomePageProviderService homePageProviderService;
+    @Inject
+    DomainObjectContainer container;
+}
+----
+<1> override the default imlpementation
+<2> if a non-null object was returned, then return this
+<3> ensure that any persisted objects have been deleted.
+<4> reach inside the Wicket viewer's internals to obtain the list of breadcrumbs.
+<5> loop over all breadcrumbs
+<6> unwrap the Wicket viewer's serializable representation of each domain object (`EntityModel`) to the Isis runtime's
+representation (`ObjectAdapter`)
+<7> unwrap the Isis runtime's representation of each domain object (`ObjectAdapter`) to the domain object pojo itself
+<8> if object is persistable (not a view model) then make sure it is not deleted
+<9> return the first object if any, otherwise the home page object (if any).
+
+Note that the above implementation uses Java 8, so if you are using Java 7 then you'll need to backport accordingly.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_how-to-implement-a-spellchecker.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_how-to-implement-a-spellchecker.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_how-to-implement-a-spellchecker.adoc
new file mode 100644
index 0000000..eebaa7d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_how-to-implement-a-spellchecker.adoc
@@ -0,0 +1,29 @@
+[[_ugbtb_hints-and-tips_how-to-implement-a-spellchecker]]
+= How to implement a spellchecker?
+: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/
+
+
+
+From this link:http://isis.markmail.org/thread/dduarjscrbnodfsi[thread] on the Apache Isis users mailing list:
+
+* _What is the easiest way to add a spell checker to the text written in a field in
+   a domain object, for instance to check English syntax?_
+
+One way to implement is to use the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[event bus]:
+
+* Set up a xref:rgcsm.adoc#_rgcsm_classes_domainevent[domain event] xref:rgcsm.adoc#_rgcsm_classes_super_AbstractSubscriber[subscriber] that can veto the changes.
+
+* if the change is made through an action, you can use xref:../rgant/rgant.adoc#_rgant-Action_domainEvent[`@Action#domainEvent()`].
+
+if if the change is made through an edit, you can use xref:../rgant/rgant.adoc#_rgant-Property_domainEvent[`@Property#domainEvent()`].
+
+You'll need some way to know which fields should be spell checked.  Two ways spring to mind:
+
+* either look at the domain event's identifier
+
+* or subclass the domain event (recommended anyway) and have those subclass events implement some sort of marker interface, eg a `SpellCheckEvent`.
+
+And you'll (obviously) also need some sort of spell checker implementation to call.
+

http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/adocs/documentation/src/main/asciidoc/guides/ugbtb/ugbtb.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/ugbtb.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/ugbtb.adoc
index 70276b2..c03eedb 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/ugbtb.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/ugbtb.adoc
@@ -47,6 +47,7 @@ include::_ugbtb_view-models.adoc[leveloffset=+1]
 include::_ugbtb_decoupling.adoc[leveloffset=+1]
 include::_ugbtb_i18n.adoc[leveloffset=+1]
 include::_ugbtb_headless-access.adoc[leveloffset=+1]
+include::_ugbtb_hints-and-tips.adoc[leveloffset=+1]
 include::_ugbtb_other-techniques.adoc[leveloffset=+1]
 include::_ugbtb_programming-model.adoc[leveloffset=+1]
 include::_ugbtb_deployment.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips.adoc
new file mode 100644
index 0000000..7bb687d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips.adoc
@@ -0,0 +1,27 @@
+[[_ugodn_hints-and-tips]]
+= Hints and Tips
+: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/
+
+
+This chapter provides some solutions for problems we've encountered ourselves or have been raised on the Apache Isis mailing lists.
+
+See also hints-n-tips chapters in the:
+
+* the xref:../dg/dg.adoc#_ugvw_hints-and-tips[Developers'] guide
+
+* the xref:../ugvw/ugvw.adoc#_ugvw_hints-and-tips[Wicket viewer] guide
+
+* the xref:../ugvro/ugvro.adoc#_ugvro_hints-and-tips[Restful Objects viewer] guide
+
+* the xref:../ugvro/ugodn.adoc#_ugodn_hints-and-tips[Datanucleus ObjectStore] guide (this chapter)
+
+* the xref:../ugsec/ugsec.adoc#_ugsec_hints-and-tips[Security] guide
+
+* the xref:../ugbtb/ugbtb.adoc#_ugbtb_hints-and-tips[Beyond the Basics] guide.
+
+
+include::_ugodn_hints-and-tips_overriding-jdo-annotations.adoc[leveloffset=+1]
+include::_ugodn_hints-and-tips_subtype-entity-not-fully-populated.adoc[leveloffset=+1]
+include::_ugodn_hints-and-tips_java8.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_java8.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_java8.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_java8.adoc
new file mode 100644
index 0000000..5f1dfed
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_java8.adoc
@@ -0,0 +1,29 @@
+[[_ugodn_hints-and-tips_java8]]
+= Java8
+: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/
+
+
+
+DataNucleus 4.x supports Java 7, but can also be used with Java 8, eg for streams support against collections managed
+by DataNucleus.
+
+Just include within `<dependencies>` of your `dom` module's `pom.xml`:
+
+[source,xml]
+----
+<dependency>
+    <groupId>org.datanucleus</groupId>
+    <artifactId>datanucleus-java8</artifactId>
+    <version>4.2.0-release</version>t
+</dependency>
+----
+
+[NOTE]
+====
+The DataNucleus website includes a link:http://www.datanucleus.org/products/accessplatform/compatibility.html[page]
+listing version compatibility of these extensions vis-a-vis the core DataNucleus platform.
+====
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_overriding-jdo-annotations.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_overriding-jdo-annotations.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_overriding-jdo-annotations.adoc
new file mode 100644
index 0000000..6fead2e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_overriding-jdo-annotations.adoc
@@ -0,0 +1,64 @@
+[[_ugodn_hints-and-tips_overriding-jdo-annotations]]
+= Overriding JDO Annotations
+: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/
+
+
+
+The JDO Objectstore (or rather, the underlying DataNucleus implementation) builds its own persistence metamodel by reading both annotations on the class and also by searching for metadata in XML files. The metadata in the XML files takes precedence over the annotations, and so can be used to override metadata that is "hard-coded" in annotations.
+
+For example, as of 1.9.0 the various http://www.isisaddons.org[Isis addons] modules (not ASF) use schemas for each entity. For example, the `AuditEntry` entity in the http://github.com/isisaddons/isis-module-audit[audit module] is annotated as:
+
+[source,java]
+----
+@javax.jdo.annotations.PersistenceCapable(
+        identityType=IdentityType.DATASTORE,
+        schema = "IsisAddonsAudit",
+        table="AuditEntry")
+public class AuditEntry {
+    ...
+}
+----
+
+This will map the `AuditEntry` class to a table `&quot;IsisAddonsAudit&quot;.&quot;AuditEntry&quot;`; that is using a custom schema to own the object.
+
+Suppose though that for whatever reason we didn't want to use a custom schema but would rather use the default. We can override the above annotation using a `package.jdo` file, for example:
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8" ?>
+<jdo xmlns="http://xmlns.jcp.org/xml/ns/jdo/jdo"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/jdo/jdo
+        http://xmlns.jcp.org/xml/ns/jdo/jdo_3_0.xsd" version="3.0">
+    <package name="org.isisaddons.module.audit.dom">
+        <class name="AuditEntry" schema="PUBLIC" table="IsisAddonsAuditEntry">
+        </class>
+    </package>
+</jdo>
+----
+
+This file should be placed can be placed in `src/main/java/META-INF` within your application's `dom` module.
+
+[TIP]
+====
+You can use a mixin action on xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins_Persistable[`Persistable`] mixin
+to download the JDO class metadata in XML form.
+====
+
+
+[NOTE]
+====
+* The same approach should work for any other JDO metadata, but some experimentation might be required.+
++
+For example, in writing up the above example we found that writing `schema=&quot;&quot;` (in an attempt to say, "use the default schema for this table") actually caused the original annotation value to be used instead.
+
+* Forcing the schema to "PUBLIC" (as in the above example) works, but it isn't ideal because the name "PUBLIC" is not vendor-neutral (it works for HSQLDB, but MS SQL Server uses "dbo" as its default).
+
+* As of 1.9.0 Apache Isis will automatically (attempt) to create the owning schema for a given table if it does not exist. This behaviour can be customized, as described in the section on xref:_ugbtb_decoupling_db-schemas[using modules].
+
+* You may need to override the entire class metadata rather than individual elements; the mixin mentioned above can help here.
+====
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_subtype-entity-not-fully-populated.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_subtype-entity-not-fully-populated.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_subtype-entity-not-fully-populated.adoc
new file mode 100644
index 0000000..90a670d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_subtype-entity-not-fully-populated.adoc
@@ -0,0 +1,60 @@
+[[_ugodn_hints-and-tips_subtype-entity-not-fully-populated]]
+= Subtype not fully populated
+: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/
+
+
+Taken from link:http://markmail.org/message/ovgai56uqgfgnrx7[this thread] on the Apache Isis users mailing list...
+
+
+If it seems that Apache Isis (or rather DataNucleus) isn't fully populating domain entities (ie leaving some properties as `null`), then check that your actions are not accessing the fields directly.
+Use getters instead.
+
+
+[WARNING]
+====
+Properties of domain entities should always be accessed using getters.
+The only code that should access to fields should be the getters themselves.
+====
+
+Why so?
+Because DataNucleus will potentially lazy load some properties, but to do this it needs to know that the field is being requested.
+This is the purpose of the enhancement phase: the bytecode of the original getter method is actually wrapped in code that does the lazy loading checking.
+But hitting the field directly means that the lazy loading code does not run.
+
+This error can be subtle: sometimes "incorrect" code that accesses the fields will seem to work.
+But that will be because the field has been populated already, for whatever reason.
+
+One case where you will find the issue highlighted is for subtype tables that have been mapped using an inheritance strategy of `NEW_TABLE`, eg:
+
+[source,java]
+----
+@javax.jdo.annotations.PersistenceCapable
+@javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.NEW_TABLE)
+public class SupertypeEntity {
+    ...
+}
+----
+
+and then:
+
+[source,java]
+----
+@javax.jdo.annotations.PersistenceCapable
+@javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.NEW_TABLE)
+public class SubtypeEntity extends SupertypeEntity {
+    ...
+}
+----
+
+This will generate two tables in the database, with the primary key of the supertype table propagated as a foreign key (also primary key) of the subtype table (sometimes called "table per type" strategy).
+This means that DataNucleus might retrieve data from only the supertype table, and the lazily load the subtype fields only as required.
+This is preferable to doing a left outer join from the super- to the subtype tables to retrieve data that might not be needed.
+
+On the other hand, if the `SUPERCLASS_TABLE` strategy (aka "table per hierarchy" or roll-up) or the `SUBCLASS_TABLE` strategy (roll-down) was used, then the problem is less likely to occur because DataNucleus would obtain all the data for any given instance from a single table.
+
+Final note: references to other objects (either scalar references or in collections) in particular require that getters rather than fields to be used to obtain them: it's hopefully obvious that DataNucleus (like all ORMs) should not and will not resolve such references (otherwise, where to stop... and the whole database would be loaded into memory).
+
+In summary, there's just one rule: *always use the getters, never the fields*.
+

http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_java8.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_java8.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_java8.adoc
deleted file mode 100644
index 64dc790..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_java8.adoc
+++ /dev/null
@@ -1,29 +0,0 @@
-[[_ugodn_java8]]
-= Java8
-: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/
-
-
-
-DataNucleus 4.x supports Java 7, but can also be used with Java 8, eg for streams support against collections managed
-by DataNucleus.
-
-Just include within `<dependencies>` of your `dom` module's `pom.xml`:
-
-[source,xml]
-----
-<dependency>
-    <groupId>org.datanucleus</groupId>
-    <artifactId>datanucleus-java8</artifactId>
-    <version>4.2.0-release</version>t
-</dependency>
-----
-
-[NOTE]
-====
-The DataNucleus website includes a link:http://www.datanucleus.org/products/accessplatform/compatibility.html[page]
-listing version compatibility of these extensions vis-a-vis the core DataNucleus platform.
-====
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_overriding-jdo-annotations.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_overriding-jdo-annotations.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_overriding-jdo-annotations.adoc
deleted file mode 100644
index fa959f9..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_overriding-jdo-annotations.adoc
+++ /dev/null
@@ -1,64 +0,0 @@
-[[_ugodn_overriding-jdo-annotations]]
-= Overriding JDO Annotations
-: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/
-
-
-
-The JDO Objectstore (or rather, the underlying DataNucleus implementation) builds its own persistence metamodel by reading both annotations on the class and also by searching for metadata in XML files. The metadata in the XML files takes precedence over the annotations, and so can be used to override metadata that is "hard-coded" in annotations.
-
-For example, as of 1.9.0 the various http://www.isisaddons.org[Isis addons] modules (not ASF) use schemas for each entity. For example, the `AuditEntry` entity in the http://github.com/isisaddons/isis-module-audit[audit module] is annotated as:
-
-[source,java]
-----
-@javax.jdo.annotations.PersistenceCapable(
-        identityType=IdentityType.DATASTORE,
-        schema = "IsisAddonsAudit",
-        table="AuditEntry")
-public class AuditEntry {
-    ...
-}
-----
-
-This will map the `AuditEntry` class to a table `&quot;IsisAddonsAudit&quot;.&quot;AuditEntry&quot;`; that is using a custom schema to own the object.
-
-Suppose though that for whatever reason we didn't want to use a custom schema but would rather use the default. We can override the above annotation using a `package.jdo` file, for example:
-
-[source,xml]
-----
-<?xml version="1.0" encoding="UTF-8" ?>
-<jdo xmlns="http://xmlns.jcp.org/xml/ns/jdo/jdo"
-    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-    xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/jdo/jdo
-        http://xmlns.jcp.org/xml/ns/jdo/jdo_3_0.xsd" version="3.0">
-    <package name="org.isisaddons.module.audit.dom">
-        <class name="AuditEntry" schema="PUBLIC" table="IsisAddonsAuditEntry">
-        </class>
-    </package>
-</jdo>
-----
-
-This file should be placed can be placed in `src/main/java/META-INF` within your application's `dom` module.
-
-[TIP]
-====
-You can use a mixin action on xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins_Persistable[`Persistable`] mixin
-to download the JDO class metadata in XML form.
-====
-
-
-[NOTE]
-====
-* The same approach should work for any other JDO metadata, but some experimentation might be required.+
-+
-For example, in writing up the above example we found that writing `schema=&quot;&quot;` (in an attempt to say, "use the default schema for this table") actually caused the original annotation value to be used instead.
-
-* Forcing the schema to "PUBLIC" (as in the above example) works, but it isn't ideal because the name "PUBLIC" is not vendor-neutral (it works for HSQLDB, but MS SQL Server uses "dbo" as its default).
-
-* As of 1.9.0 Apache Isis will automatically (attempt) to create the owning schema for a given table if it does not exist. This behaviour can be customized, as described in the section on xref:_ugbtb_decoupling_db-schemas[using modules].
-
-* You may need to override the entire class metadata rather than individual elements; the mixin mentioned above can help here.
-====
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/adocs/documentation/src/main/asciidoc/guides/ugodn/ugodn.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/ugodn.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/ugodn.adoc
index f10d3cd..03887c2 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugodn/ugodn.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugodn/ugodn.adoc
@@ -59,6 +59,5 @@ The remaining guides are:
 
 include::_ugodn_configuring.adoc[leveloffset=+1]
 include::_ugodn_jdo-mappings.adoc[leveloffset=+1]
-include::_ugodn_overriding-jdo-annotations.adoc[leveloffset=+1]
-include::_ugodn_java8.adoc[leveloffset=+1]
+include::_ugodn_hints-and-tips.adoc[leveloffset=+1]
 

http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_configuring-isis-to-use-bypass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_configuring-isis-to-use-bypass.adoc b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_configuring-isis-to-use-bypass.adoc
deleted file mode 100644
index 734e0e3..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_configuring-isis-to-use-bypass.adoc
+++ /dev/null
@@ -1,23 +0,0 @@
-[[_ugsec_configuring-isis-to-use-bypass]]
-= Bypassing 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/
-
-
-The bypass security component consists of an implementation of both the `AuthenticationManager` and `AuthorizationManager` APIs, and are intended for prototyping use only.
-
-The authentication manager allows access with any credentials (in a sense, "bypassing" authentication), while the authorization manager provides access to all class members (in a sense, "bypassing" authorization).
-
-
-To tell Apache Isis to bypass security, just update the `WEB-INF/isis.properties` file:
-
-[source,ini]
-----
-isis.authentication=bypass
-isis.authorization=bypass
-----
-
-This installs the appropriate no-op implementations for both authentication and authorization:
-
-image::{_imagesdir}security/security-apis-impl/configure-isis-to-use-bypass.PNG[width="600px"]

http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_hints-and-tips.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_hints-and-tips.adoc b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_hints-and-tips.adoc
new file mode 100644
index 0000000..94eb956
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_hints-and-tips.adoc
@@ -0,0 +1,28 @@
+[[_ugsec_hints-and-tips]]
+= Hints and Tips
+: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/
+:toc: right
+
+
+
+This chapter provides some solutions for problems we've encountered ourselves or have been raised on the Apache Isis mailing lists.
+
+See also hints-n-tips chapters in the:
+
+* the xref:../dg/dg.adoc#_ugvw_hints-and-tips[Developers'] guide
+
+* the xref:../ugvw/ugvw.adoc#_ugvw_hints-and-tips[Wicket viewer] guide
+
+* the xref:../ugvro/ugvro.adoc#_ugvro_hints-and-tips[Restful Objects viewer] guide
+
+* the xref:../ugvro/ugodn.adoc#_ugodn_hints-and-tips[Datanucleus ObjectStore] guide
+
+* the xref:../ugsec/ugsec.adoc#_ugsec_hints-and-tips[Security] guide (this chapter)
+
+* the xref:../ugbtb/ugbtb.adoc#_ugbtb_hints-and-tips[Beyond the Basics] guide.
+
+
+
+include::_ugsec_hints-and-tips_configuring-isis-to-use-bypass.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_hints-and-tips_configuring-isis-to-use-bypass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_hints-and-tips_configuring-isis-to-use-bypass.adoc b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_hints-and-tips_configuring-isis-to-use-bypass.adoc
new file mode 100644
index 0000000..9f297c8
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_hints-and-tips_configuring-isis-to-use-bypass.adoc
@@ -0,0 +1,23 @@
+[[_ugsec_hints-and-tips_configuring-isis-to-use-bypass]]
+= Bypassing 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/
+
+
+The bypass security component consists of an implementation of both the `AuthenticationManager` and `AuthorizationManager` APIs, and are intended for prototyping use only.
+
+The authentication manager allows access with any credentials (in a sense, "bypassing" authentication), while the authorization manager provides access to all class members (in a sense, "bypassing" authorization).
+
+
+To tell Apache Isis to bypass security, just update the `WEB-INF/isis.properties` file:
+
+[source,ini]
+----
+isis.authentication=bypass
+isis.authorization=bypass
+----
+
+This installs the appropriate no-op implementations for both authentication and authorization:
+
+image::{_imagesdir}security/security-apis-impl/configure-isis-to-use-bypass.PNG[width="600px"]

http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/adocs/documentation/src/main/asciidoc/guides/ugsec/ugsec.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugsec/ugsec.adoc b/adocs/documentation/src/main/asciidoc/guides/ugsec/ugsec.adoc
index b12e3c7..449abb5 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugsec/ugsec.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugsec/ugsec.adoc
@@ -92,7 +92,8 @@ include::_ugsec_shiro-jdbc-realm.adoc[leveloffset=+1]
 
 include::_ugsec_shiro-isis-enhanced-wildcard-permission.adoc[leveloffset=+1]
 
-include::_ugsec_configuring-isis-to-use-bypass.adoc[leveloffset=+1]
+
+include::_ugsec_hints-and-tips.adoc[leveloffset=+1]
 
 include::_ugsec_api-for-applications.adoc[leveloffset=+1]
 

http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips.adoc
index ac454f9..a53db8a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips.adoc
@@ -5,92 +5,33 @@
 :_imagesdir: images/
 
 
+This chapter provides some solutions for problems we've encountered ourselves or have been raised on the Apache Isis mailing lists.
 
-Since the Restful Objects viewer is designed for computer programs to interact with (rather than human beings), it can be a little difficult to explore and generally "grok" how it works.
-
-This section provides a few hints-and-tips to help you on your way.
-
-
-
-
-== Using Chrome Tools
-
-This link:https://www.youtube.com/watch?v=_-TOvVYWCHc[screencast] shows how to explore the Restful API using Chrome plugins/extensions, and how we use them to write end-2-end (TCK) tests for the Restful Objects viewer.
-
-
-
-
+See also hints-n-tips chapters in the:
 
-== Angular Tips
+* the xref:../dg/dg.adoc#_ugvw_hints-and-tips[Developers'] guide
 
-The hypermedia API exposed by Apache Isis' Restful Objects viewer is intended be support both bespoke custom-written viewers as well as generic viewers. Indeed, we expect most clients consuming the API will be bespoke, not generic.
+* the xref:../ugvw/ugvw.adoc#_ugvw_hints-and-tips[Wicket viewer] guide
 
-This page captures one or two tips on using Angular to write such a bespoke client.
+* the xref:../ugvro/ugvro.adoc#_ugvro_hints-and-tips[Restful Objects viewer] guide (this chapter)
 
+* the xref:../ugvro/ugodn.adoc#_ugodn_hints-and-tips[Datanucleus ObjectStore] guide
 
-=== Invoking a GET link (eg invoking a query action)
+* the xref:../ugsec/ugsec.adoc#_ugsec_hints-and-tips[Security] guide
 
-Suppose you have a `CustomerService` providing a `findCustomer` action:
-
-[source,java]
-----
-public class CustomerService {
-    public String id() { return "customers"; }
-    @Action(semantics=SemanticsOf.SAFE)
-    public Customer findCustomer(
-            @ParameterLayout(named="customerName")
-            final String customerName) {
-        ...
-    }
-}
-----
-
-Restful Objects will expose this as action with the following link that looks something like:
-
-[source,javascript]
-----
-{
-  "rel" : "urn:org.restfulobjects:rels/invoke",
-  "href" : "http://localhost:8080/restful/services/customers/actions/findCustomer/invoke",
-  "method" : "GET",
-  "type" : "application/json;profile=\"urn:org.restfulobjects:repr-types/action-result\"",
-  "arguments" : {
-    "customerName" : {
-      "value" : null
-    }
-  }
-}
-----
-
-You can then invoke this using Angular' `$resource` service as follows.
-
-[source,javascript]
-----
-var findCustomer = $resource("http://localhost:8080/restful/services/customers/actions/findCustomer/invoke?:queryString");
-var findCustomerArgs = {
-  "customerName": {
-      "value": "Fred"
-    }
-};
-findCustomer.get({queryString: JSON.stringify(findCustomerArgs)}, function(data) { ... } )
-----
-
-Here the `:queryString` placeholder in the initial `$resource` constructor is expanded with a stringified version of the JSON object representing the args. Note how the `findCustomerArgs` is the same as the `&quot;arguments&quot;` attribute in the original link (with a value provided instead of `null`).
-
-
-=== Invoking a PUT or POST link
-
-If the method is a PUT or a POST, then no `:queryString` placeholder is required in the URL, and the args are instead part of the body.
-
-Use `$resource.put(...)` or `$resource.post(...)` instead.
+* the xref:../ugbtb/ugbtb.adoc#_ugbtb_hints-and-tips[Beyond the Basics] guide.
 
 
+Since the Restful Objects viewer is designed for computer programs to interact with (rather than human beings), it can be a little difficult to explore and generally "grok" how it works.
 
-== Pretty printing
+This section provides a few hints-and-tips to help you on your way.
 
-The JSON representations generated by the Restful Objects viewer are in compact form if the xref:../rgcfg/rgcfg.adoc#_rgcfg_deployment-types[deployment type] is SERVER (ie production), but will automatically be "pretty printed" (in other words indented) if the deployment type is PROTOTYPE.
 
 
+include::_ugvro_hints-and-tips_using-chrome-devtools.adoc[leveloffset=+1]
+include::_ugvro_hints-and-tips_angular-tips.adoc[leveloffset=+1]
+include::_ugvro_hints-and-tips_pretty-printing.adoc[leveloffset=+1]
+include::_ugvro_hints-and-tips_restful-image-property.adoc[leveloffset=+1]
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips_angular-tips.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips_angular-tips.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips_angular-tips.adoc
new file mode 100644
index 0000000..1ad8f1e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips_angular-tips.adoc
@@ -0,0 +1,69 @@
+[[_ugvro_hints-and-tips_angular-tips]]
+= Angular Tips
+: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/
+
+
+
+The hypermedia API exposed by Apache Isis' Restful Objects viewer is intended be support both bespoke custom-written viewers as well as generic viewers. Indeed, we expect most clients consuming the API will be bespoke, not generic.
+
+This page captures one or two tips on using Angular to write such a bespoke client.
+
+
+== Invoking a GET link (eg invoking a query action)
+
+Suppose you have a `CustomerService` providing a `findCustomer` action:
+
+[source,java]
+----
+public class CustomerService {
+    public String id() { return "customers"; }
+    @Action(semantics=SemanticsOf.SAFE)
+    public Customer findCustomer(
+            @ParameterLayout(named="customerName")
+            final String customerName) {
+        ...
+    }
+}
+----
+
+Restful Objects will expose this as action with the following link that looks something like:
+
+[source,javascript]
+----
+{
+  "rel" : "urn:org.restfulobjects:rels/invoke",
+  "href" : "http://localhost:8080/restful/services/customers/actions/findCustomer/invoke",
+  "method" : "GET",
+  "type" : "application/json;profile=\"urn:org.restfulobjects:repr-types/action-result\"",
+  "arguments" : {
+    "customerName" : {
+      "value" : null
+    }
+  }
+}
+----
+
+You can then invoke this using Angular' `$resource` service as follows.
+
+[source,javascript]
+----
+var findCustomer = $resource("http://localhost:8080/restful/services/customers/actions/findCustomer/invoke?:queryString");
+var findCustomerArgs = {
+  "customerName": {
+      "value": "Fred"
+    }
+};
+findCustomer.get({queryString: JSON.stringify(findCustomerArgs)}, function(data) { ... } )
+----
+
+Here the `:queryString` placeholder in the initial `$resource` constructor is expanded with a stringified version of the JSON object representing the args. Note how the `findCustomerArgs` is the same as the `&quot;arguments&quot;` attribute in the original link (with a value provided instead of `null`).
+
+
+== Invoking a PUT or POST link
+
+If the method is a PUT or a POST, then no `:queryString` placeholder is required in the URL, and the args are instead part of the body.
+
+Use `$resource.put(...)` or `$resource.post(...)` instead.
+

http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips_pretty-printing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips_pretty-printing.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips_pretty-printing.adoc
new file mode 100644
index 0000000..22108b4
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips_pretty-printing.adoc
@@ -0,0 +1,13 @@
+[[_ugvro_hints-and-tips_pretty-printing]]
+= Pretty printing
+: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/
+
+
+The JSON representations generated by the Restful Objects viewer are in compact form if the xref:../rgcfg/rgcfg.adoc#_rgcfg_deployment-types[deployment type] is SERVER (ie production), but will automatically be "pretty printed" (in other words indented) if the deployment type is PROTOTYPE.
+
+
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips_restful-image-property.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips_restful-image-property.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips_restful-image-property.adoc
new file mode 100644
index 0000000..898df04
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips_restful-image-property.adoc
@@ -0,0 +1,25 @@
+[[_ugvro_hints-and-tips_restful-image-property]]
+= How parse images in RO viewer?
+: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/
+
+
+From this link:http://markmail.org/message/4kcu7sml4ufdsah3[thread] on the Apache Isis users mailing list:
+
+* _I am trying to display an image in a JavaScript client app, the image comes from
+   an Isis RO web service as a string, but it won't show.
+Is there something I should do to change the message?_
+
+
+The RO viewer returns the image as a string, in the form:
+
+    "Tacos.jpg:image/jpeg:/9j//4AAQSkZJRgABAQEAlgCWAAD/  ...."
+
+This is in the form:
+
+    (filename):(mime type):(binary data in base64)
+
+This is basically the xref:../rgcms/rgcms.adoc#_rgcms_classes_value-types_Blob[`Blob`] value type, in string form.
+
+To use, split the parts then format the mime type and base64 data correctly before using as source in an `<img>` tag.

http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips_using-chrome-devtools.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips_using-chrome-devtools.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips_using-chrome-devtools.adoc
new file mode 100644
index 0000000..74eb6b8
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips_using-chrome-devtools.adoc
@@ -0,0 +1,9 @@
+[[_ugvro_hints-and-tips_using-chrome-devtools]]
+= Using Chrome Dev Tools
+: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/
+
+
+
+This link:https://www.youtube.com/watch?v=_-TOvVYWCHc[screencast] shows how to explore the Restful API using Chrome plugins/extensions, and how we use them to write end-2-end (TCK) tests for the Restful Objects viewer.

http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_extending_custom-bootstrap-theme.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_extending_custom-bootstrap-theme.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_extending_custom-bootstrap-theme.adoc
index e52d7d5..b837fa6 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_extending_custom-bootstrap-theme.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_extending_custom-bootstrap-theme.adoc
@@ -10,7 +10,7 @@ The Apache Isis Wicket viewer uses http://getbootstrap.com/[Bootstrap] styles an
 
 By default the viewer uses the default bootstrap theme. It is possible to configure the Wicket viewer to allow the user to xref:../ugvw/ugvw.adoc#_ugvw_configuration-properties_showing-theme-chooser[select other themes] provided by http://bootswatch.com[bootswatch.com], and if required one of these can be xref:../ugvw/ugvw.adoc#_ugvw_customisation_default-theme[set as the default].
 
-However, you may instead want to write your own custom theme, for example to fit your company's look-n-feel/interface guidelines. This is done by implementing https://github.com/l0rdn1kk0n/wicket-bootstrap[Wicket Bootstrap]\u2019s `de.agilecoders.wicket.core.settings.ITheme` class. This defines:
+However, you may instead want to write your own custom theme, for example to fit your company's look-n-feel/interface guidelines. This is done by implementing https://github.com/l0rdn1kk0n/wicket-bootstrap[Wicket Bootstrap]'s `de.agilecoders.wicket.core.settings.ITheme` class. This defines:
 
 * the name of the theme
 * the resources it needs (the CSS and optional JS and/or fonts), and

http://git-wip-us.apache.org/repos/asf/isis/blob/fcf368f0/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_hints-and-tips.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_hints-and-tips.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_hints-and-tips.adoc
new file mode 100644
index 0000000..c736afb
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_hints-and-tips.adoc
@@ -0,0 +1,31 @@
+[[_ugvro_hints-and-tips]]
+= Hints and Tips
+: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/
+
+
+
+This chapter provides some solutions for problems we've encountered ourselves or have been raised on the Apache Isis mailing lists.
+
+See also hints-n-tips chapters in the:
+
+* the xref:../dg/dg.adoc#_ugvw_hints-and-tips[Developers'] guide
+
+* the xref:../ugvw/ugvw.adoc#_ugvw_hints-and-tips[Wicket viewer] guide (this chapter)
+
+* the xref:../ugvro/ugvro.adoc#_ugvro_hints-and-tips[Restful Objects viewer] guide
+
+* the xref:../ugvro/ugodn.adoc#_ugodn_hints-and-tips[Datanucleus ObjectStore] guide
+
+* the xref:../ugsec/ugsec.adoc#_ugsec_hints-and-tips[Security] guide
+
+* the xref:../ugbtb/ugbtb.adoc#_ugbtb_hints-and-tips[Beyond the Basics] guide.
+
+
+
+include::_ugvw_hints-and-tips_per-user-themes.adoc[leveloffset=+1]
+include::_ugvw_hints-and-tips_i18n-label-in-wicket-viewer.adoc[leveloffset=+1]
+
+
+

[31/58] [abbrv] isis git commit: ISIS-1521: fixes further xref links between guides

[da...@apache.org]

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Mixin.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Mixin.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Mixin.adoc
index 92b1acf..03abb65 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Mixin.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Mixin.adoc
@@ -11,7 +11,7 @@ The `@Mixin` annotation indicates that the class acts as a mixin, contributing b
 Mixins were originally introduced as a means of allowing contributions from one module to the types of another module; in such cases the mixin type is often an interface type (eg `DocumentHolder`) that might be implemented by numerous different concrete types.
 However, mixins are also a convenient mechanism for grouping functionality even for a concrete type.
 
-For further discussion on using mixins, see xref:ugbtb.adoc#_ugbtb_decoupling_mixins[mixins] in the user guide.
+For further discussion on using mixins, see xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_mixins[mixins] in the user guide.
 
 The table below summarizes the annotation's attributes.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout.adoc
index 6761765..bba6565 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout.adoc
@@ -96,7 +96,7 @@ public class ToDoItem {
 
 [NOTE]
 ====
-Note that there is (currently) no support for specifying UI hints for domain services through the dynamic xref:ugvw.adoc#_ugvw_layout_file-based[`.layout.json`] file (only for properties, collections and actions are supported).
+Note that there is (currently) no support for specifying UI hints for domain services through the dynamic xref:../ugvw/ugvw.adoc#_ugvw_layout_file-based[`.layout.json`] file (only for properties, collections and actions are supported).
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_describedAs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_describedAs.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_describedAs.adoc
index b4ab0da..a25df4a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_describedAs.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_describedAs.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-The `describedAs()` attribute is used to provide a short description of the action parameter to the user.  In the xref:ugvw.adoc#[Wicket viewer] it is displayed as a 'tool tip'.  The `describedAs()` attribute can also be specified for xref:../rgant/rgant.adoc#_rgant-CollectionLayout_describedAs[collections],  xref:../rgant/rgant.adoc#_rgant-PropertyLayout_describedAs[properties], xref:../rgant/rgant.adoc#_rgant-ActionLayout_describedAs[actions], xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_describedAs[domain objects] and xref:../rgant/rgant.adoc#_rgant-ViewModelLayout_describedAs[view models].
+The `describedAs()` attribute is used to provide a short description of the action parameter to the user.  In the xref:../ugvw/ugvw.adoc#[Wicket viewer] it is displayed as a 'tool tip'.  The `describedAs()` attribute can also be specified for xref:../rgant/rgant.adoc#_rgant-CollectionLayout_describedAs[collections],  xref:../rgant/rgant.adoc#_rgant-PropertyLayout_describedAs[properties], xref:../rgant/rgant.adoc#_rgant-ActionLayout_describedAs[actions], xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_describedAs[domain objects] and xref:../rgant/rgant.adoc#_rgant-ViewModelLayout_describedAs[view models].
 
 Descriptions may be provided for objects, members (properties,
 collections and actions), and for individual parameters within an action

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_labelPosition.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_labelPosition.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_labelPosition.adoc
index 0242245..610b0ed 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_labelPosition.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_labelPosition.adoc
@@ -36,6 +36,6 @@ public class Order {
 ----
 
 
-To get an idea of how these are rendered (in the xref:ugvw.adoc#[Wicket viewer]), see xref:../rgant/rgant.adoc#_rgant-PropertyLayout_labelPosition[PropertyLayout#labelPosition()].
+To get an idea of how these are rendered (in the xref:../ugvw/ugvw.adoc#[Wicket viewer]), see xref:../rgant/rgant.adoc#_rgant-PropertyLayout_labelPosition[PropertyLayout#labelPosition()].
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_named.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_named.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_named.adoc
index b34662f..8070b24 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_named.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_named.adoc
@@ -40,5 +40,5 @@ public class Customer {
 
 [TIP]
 ====
-The framework also provides a separate, powerful mechanism for xref:ugbtb.adoc#_ugbtb_i18n[internationalization].
+The framework also provides a separate, powerful mechanism for xref:../ugbtb/ugbtb.adoc#_ugbtb_i18n[internationalization].
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_typicalLength.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_typicalLength.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_typicalLength.adoc
index bcc9c7c..434a776 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_typicalLength.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ParameterLayout_typicalLength.adoc
@@ -8,7 +8,7 @@
 
 The `typicalLength()` attribute indicates the typical length of a string parameter.  It is ignored for parameters of other types.  The attribute is also supported for xref:../rgant/rgant.adoc#_rgant-PropertyLayout_typicalLength[properties].
 
-The information is intended as a hint to the UI to determine the space that should be given to render a particular string parameter.  That said, note that the xref:ugvw.adoc#[Wicket viewer] uses the maximum space available for all fields, so in effect ignores this attribute.
+The information is intended as a hint to the UI to determine the space that should be given to render a particular string parameter.  That said, note that the xref:../ugvw/ugvw.adoc#[Wicket viewer] uses the maximum space available for all fields, so in effect ignores this attribute.
 
 For example:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PersistenceCapable.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PersistenceCapable.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PersistenceCapable.adoc
index 5e42bfa..f363421 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PersistenceCapable.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PersistenceCapable.adoc
@@ -25,8 +25,8 @@ This can appear in several contexts, including:
  (see xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`])
  ** and thus in the "table-of-two-halves" pattern, as per (non-ASF) http://github.com/isisaddons/isis-module-poly[Isis addons' poly] module
 * in the serialization of `OidDto` in the xref:../rgcms/rgcms.adoc#_rgcms_schema-cmd[command] and xref:../rgcms/rgcms.adoc#_rgcms_schema-ixn[interaction] schemas
-* in the URLs of the xref:ugvro.adoc#[RestfulObjects viewer]
-* in the URLs of the xref:ugvw.adoc#[Wicket viewer] (in general and in particular if xref:ugvw.adoc#_ugvw_features_hints-and-copy-url[copying URLs])
+* in the URLs of the xref:../ugvro/ugvro.adoc#[RestfulObjects viewer]
+* in the URLs of the xref:../ugvw/ugvw.adoc#[Wicket viewer] (in general and in particular if xref:../ugvw/ugvw.adoc#_ugvw_features_hints-and-copy-url[copying URLs])
 * in XML snapshots generated by the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_XmlSnapshotService[`XmlSnapshotService`]
 
 
@@ -92,7 +92,7 @@ If only `schema` is defined, then the value is "`schema.className`".
 This might be obvious, but to make explicit: we recommend that you always specify an object type for your domain objects.
 
 Otherwise, if you refactor your code (change class name or move package), then any externally held references to the OID of the object will break.
-At best this will require a data migration in the database; at worst it could cause external clients accessing data through the xref:ugvro.adoc#[Restful Objects] viewer to break.
+At best this will require a data migration in the database; at worst it could cause external clients accessing data through the xref:../ugvro/ugvro.adoc#[Restful Objects] viewer to break.
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PostConstruct.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PostConstruct.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PostConstruct.adoc
index 4af546d..78d60f7 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PostConstruct.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PostConstruct.adoc
@@ -7,7 +7,7 @@
 
 The `@javax.annotation.PostConstruct` annotation, as defined in link:https://jcp.org/en/jsr/detail?id=250[JSR-250],  is recognized by Apache Isis as a callback method on domain services to be called just after they have been constructed, in order that they initialize themselves.
 
-It is also recognized for xref:ugbtb.adoc#_ugbtb_view-models[view models] (eg annotated with xref:../rgant/rgant.adoc#_rgant-ViewModel[`@ViewModel`]).
+It is also recognized for xref:../ugbtb/ugbtb.adoc#_ugbtb_view-models[view models] (eg annotated with xref:../rgant/rgant.adoc#_rgant-ViewModel[`@ViewModel`]).
 
 For the default application-scoped (singleton) domain services, this means that the method, if present, is called during the bootstrapping of the application.  For xref:../rgant/rgant.adoc#_rgant-RequestScoped[`@RequestScoped`] domain services, the method is called at the beginning of the request.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout.adoc
index 96517ee..15b43b5 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout.adoc
@@ -104,7 +104,7 @@ It is also possible to apply the annotation to actions of domain services that a
 
 [TIP]
 ====
-As an alternative to using the `@PropertyLayout` annotation, a xref:ugvw.adoc#_ugvw_layout_file-based[file-based layout] can be used (and is generally to be preferred since it is more flexible/powerful).
+As an alternative to using the `@PropertyLayout` annotation, a xref:../ugvw/ugvw.adoc#_ugvw_layout_file-based[file-based layout] can be used (and is generally to be preferred since it is more flexible/powerful).
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_cssClass.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_cssClass.adoc
index c5580e8..acd69a0 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_cssClass.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_cssClass.adoc
@@ -23,7 +23,7 @@ public class ToDoItem {
 
 
 
-As an alternative to using the annotation, the dynamic xref:ugvw.adoc#_ugvw_layout_file-based[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:../ugvw/ugvw.adoc#_ugvw_layout_file-based[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_describedAs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_describedAs.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_describedAs.adoc
index 5644f47..bbc427c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_describedAs.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_describedAs.adoc
@@ -6,7 +6,7 @@
 
 
 
-The `describedAs()` attribute is used to provide a short description of the property to the user.  In the xref:ugvw.adoc#[Wicket viewer] it is displayed as a 'tool tip'. The attribute can also be specified for xref:../rgant/rgant.adoc#_rgant-CollectionLayout_describedAs[collections],  xref:../rgant/rgant.adoc#_rgant-ActionLayout_describedAs[actions], xref:../rgant/rgant.adoc#_rgant-ParameterLayout_describedAs[parameters], xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_describedAs[domain objects] and xref:../rgant/rgant.adoc#_rgant-ViewModelLayout_describedAs[view models].
+The `describedAs()` attribute is used to provide a short description of the property to the user.  In the xref:../ugvw/ugvw.adoc#[Wicket viewer] it is displayed as a 'tool tip'. The attribute can also be specified for xref:../rgant/rgant.adoc#_rgant-CollectionLayout_describedAs[collections],  xref:../rgant/rgant.adoc#_rgant-ActionLayout_describedAs[actions], xref:../rgant/rgant.adoc#_rgant-ParameterLayout_describedAs[parameters], xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_describedAs[domain objects] and xref:../rgant/rgant.adoc#_rgant-ViewModelLayout_describedAs[view models].
 
 For example:
 
@@ -20,7 +20,7 @@ public class Customer {
 ----
 
 
-As an alternative to using the annotation, the dynamic xref:ugvw.adoc#_ugvw_layout_file-based[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:../ugvw/ugvw.adoc#_ugvw_layout_file-based[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_hidden.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_hidden.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_hidden.adoc
index 3391532..cf21719 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_hidden.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_hidden.adoc
@@ -10,7 +10,7 @@ The `hidden()` attribute indicates where (in the UI) the property should be hidd
 
 [TIP]
 ====
-It is also possible to use xref:../rgant/rgant.adoc#_rgant-PropertyLayout_hidden[`@PropertyLayout#hidden()`] or a xref:ugvw.adoc#_ugvw_layout_file-based[file-based layout] such that the property can be hidden at the view layer.
+It is also possible to use xref:../rgant/rgant.adoc#_rgant-PropertyLayout_hidden[`@PropertyLayout#hidden()`] or a xref:../ugvw/ugvw.adoc#_ugvw_layout_file-based[file-based layout] such that the property can be hidden at the view layer.
 Both options are provided with a view that in the future the view-layer semantics may be under the control of (expert) users, whereas domain-layer semantics should never be overridden or modified by the user.
 ====
 
@@ -64,11 +64,11 @@ tables. Annotating with `@Property(where=Where.NOWHERE)` overrides this.
 
 [NOTE]
 ====
-The xref:ugvro.adoc#[RestfulObjects viewer] has only partial support for these `Where` enums.
+The xref:../ugvro/ugvro.adoc#[RestfulObjects viewer] has only partial support for these `Where` enums.
 ====
 
 
-As an alternative to using the annotation, the dynamic xref:ugvw.adoc#_ugvw_layout_file-based[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:../ugvw/ugvw.adoc#_ugvw_layout_file-based[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_labelPosition.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_labelPosition.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_labelPosition.adoc
index 0b5a843..b1504fe 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_labelPosition.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_labelPosition.adoc
@@ -30,7 +30,7 @@ public class ToDoItem {
 ----
 
 
-To get an idea of how these are rendered (in the xref:ugvw.adoc#[Wicket viewer]), we can look at the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] that happens to have examples of most of these various label positions.
+To get an idea of how these are rendered (in the xref:../ugvw/ugvw.adoc#[Wicket viewer]), we can look at the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] that happens to have examples of most of these various label positions.
 
 The default `LEFT` label positioning is used by the `cost` property:
 
@@ -58,7 +58,7 @@ image::{_imagesdir}reference-annotations/PropertyLayout/labelPosition-boolean-RI
 
 
 
-As an alternative to using the annotation, the dynamic xref:ugvw.adoc#_ugvw_layout_file-based[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:../ugvw/ugvw.adoc#_ugvw_layout_file-based[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_multiLine.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_multiLine.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_multiLine.adoc
index 57da035..20dc3ac 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_multiLine.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_multiLine.adoc
@@ -25,7 +25,7 @@ Here the `stepsToReproduce` will be displayed in a text area of 10 rows.
 
 
 
-As an alternative to using the annotation, the dynamic xref:ugvw.adoc#_ugvw_layout_file-based[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:../ugvw/ugvw.adoc#_ugvw_layout_file-based[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_named.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_named.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_named.adoc
index 5cef62f..b009165 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_named.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_named.adoc
@@ -31,7 +31,7 @@ public class ToDoItem {
 
 
 
-As an alternative to using the annotation, the dynamic xref:ugvw.adoc#_ugvw_layout_file-based[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:../ugvw/ugvw.adoc#_ugvw_layout_file-based[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]
@@ -47,5 +47,5 @@ can be used instead, eg:
 
 [TIP]
 ====
-The framework also provides a separate, powerful mechanism for xref:ugbtb.adoc#_ugbtb_i18n[internationalization].
+The framework also provides a separate, powerful mechanism for xref:../ugbtb/ugbtb.adoc#_ugbtb_i18n[internationalization].
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_renderedAsDayBefore.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_renderedAsDayBefore.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_renderedAsDayBefore.adoc
index f4451af..6f8266a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_renderedAsDayBefore.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_renderedAsDayBefore.adoc
@@ -32,7 +32,7 @@ public class Tenancy {
 
 
 
-As an alternative to using the annotation, the dynamic xref:ugvw.adoc#_ugvw_layout_file-based[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:../ugvw/ugvw.adoc#_ugvw_layout_file-based[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_typicalLength.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_typicalLength.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_typicalLength.adoc
index 0d51135..5ffdc03 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_typicalLength.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PropertyLayout_typicalLength.adoc
@@ -8,7 +8,7 @@
 
 The `typicalLength()` attribute indicates the typical length of a string property.  It is ignored for properties of other types.  The attribute is also supported for xref:../rgant/rgant.adoc#_rgant-ParameterLayout_typicalLength[parameters].
 
-The information is intended as a hint to the UI to determine the space that should be given to render a particular string property.  That said, note that the xref:ugvw.adoc#[Wicket viewer] uses the maximum space available for all fields, so in effect ignores this attribute.
+The information is intended as a hint to the UI to determine the space that should be given to render a particular string property.  That said, note that the xref:../ugvw/ugvw.adoc#[Wicket viewer] uses the maximum space available for all fields, so in effect ignores this attribute.
 
 For example:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_hidden.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_hidden.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_hidden.adoc
index 71a7461..6b9aa83 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_hidden.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_hidden.adoc
@@ -62,5 +62,5 @@ tables. Annotating with `@Property(where=Where.NOWHERE)` overrides this.
 
 [NOTE]
 ====
-The xref:ugvro.adoc#[RestfulObjects viewer] has only partial support for these `Where` enums.
+The xref:../ugvro/ugvro.adoc#[RestfulObjects viewer] has only partial support for these `Where` enums.
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout.adoc
index 21f16ac..8526bb0 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout.adoc
@@ -82,7 +82,7 @@ public class CategoryPieChart { ... }
 
 [NOTE]
 ====
-Note that there is (currently) no support for specifying UI hints for view models through the dynamic xref:ugvw.adoc#_ugvw_layout_file-based[`.layout.json`] file (only for properties, collections and actions are supported).
+Note that there is (currently) no support for specifying UI hints for view models through the dynamic xref:../ugvw/ugvw.adoc#_ugvw_layout_file-based[`.layout.json`] file (only for properties, collections and actions are supported).
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout_describedAs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout_describedAs.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout_describedAs.adoc
index 1646f4e..97826b7 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout_describedAs.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout_describedAs.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-The `describedAs()` attribute is used to provide a short description of the view model to the user.  In the xref:ugvw.adoc#[Wicket viewer] it is displayed as a 'tool tip'.  The `describedAs()` attribute can also be specified for xref:../rgant/rgant.adoc#_rgant-CollectionLayout_describedAs[collections],  xref:../rgant/rgant.adoc#_rgant-PropertyLayout_describedAs[properties], xref:../rgant/rgant.adoc#_rgant-ActionLayout_describedAs[actions], xref:../rgant/rgant.adoc#_rgant-ParameterLayout_describedAs[parameters] and xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_describedAs[domain objects].
+The `describedAs()` attribute is used to provide a short description of the view model to the user.  In the xref:../ugvw/ugvw.adoc#[Wicket viewer] it is displayed as a 'tool tip'.  The `describedAs()` attribute can also be specified for xref:../rgant/rgant.adoc#_rgant-CollectionLayout_describedAs[collections],  xref:../rgant/rgant.adoc#_rgant-PropertyLayout_describedAs[properties], xref:../rgant/rgant.adoc#_rgant-ActionLayout_describedAs[actions], xref:../rgant/rgant.adoc#_rgant-ParameterLayout_describedAs[parameters] and xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_describedAs[domain objects].
 
 For example:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout_named.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout_named.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout_named.adoc
index 2998e40..606045f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout_named.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout_named.adoc
@@ -31,5 +31,5 @@ public class PieChartAnalysisViewModel {
 
 [TIP]
 ====
-The framework also provides a separate, powerful mechanism for xref:ugbtb.adoc#_ugbtb_i18n[internationalization].
+The framework also provides a separate, powerful mechanism for xref:../ugbtb/ugbtb.adoc#_ugbtb_i18n[internationalization].
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout_paged.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout_paged.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout_paged.adoc
index 6ba7e74..358f404 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout_paged.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModelLayout_paged.adoc
@@ -11,7 +11,7 @@ The `paged()` attribute specifies the number of rows to display in a standalone
 
 [WARNING]
 ====
-The xref:ugvro.adoc#[RestfulObjects viewer] currently does not support paging.   The xref:ugvw.adoc#[Wicket viewer] _does_ support paging, but note that the paging is performed client-side rather than server-side.
+The xref:../ugvro/ugvro.adoc#[RestfulObjects viewer] currently does not support paging.   The xref:../ugvw/ugvw.adoc#[Wicket viewer] _does_ support paging, but note that the paging is performed client-side rather than server-side.
 
 We therefore recommend that large collections should instead be modelled as actions (to allow filtering to be applied to limit the number of rows).
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModel_objectType.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModel_objectType.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModel_objectType.adoc
index 1ed0889..47818bf 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModel_objectType.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModel_objectType.adoc
@@ -14,8 +14,8 @@ This can appear in several contexts, including:
  (see xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`])
  ** and thus in the "table-of-two-halves" pattern, as per (non-ASF) http://github.com/isisaddons/isis-module-poly[Isis addons' poly] module
 * in the serialization of `OidDto` in the xref:../rgcms/rgcms.adoc#_rgcms_schema-cmd[command] and xref:../rgcms/rgcms.adoc#_rgcms_schema-ixn[interaction] schemas
-* in the URLs of the xref:ugvro.adoc#[RestfulObjects viewer]
-* in the URLs of the xref:ugvw.adoc#[Wicket viewer] (in general and in particular if xref:ugvw.adoc#_ugvw_features_hints-and-copy-url[copying URLs])
+* in the URLs of the xref:../ugvro/ugvro.adoc#[RestfulObjects viewer]
+* in the URLs of the xref:../ugvw/ugvw.adoc#[Wicket viewer] (in general and in particular if xref:../ugvw/ugvw.adoc#_ugvw_features_hints-and-copy-url[copying URLs])
 * in XML snapshots generated by the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_XmlSnapshotService[`XmlSnapshotService`]
 
 
@@ -54,7 +54,7 @@ If only `schema` is defined, then the value is "`schema.className`".
 This might be obvious, but to make explicit: we recommend that you always specify an object type for your domain objects.
 
 Otherwise, if you refactor your code (change class name or move package), then any externally held references to the OID of the object will break.
-At best this will require a data migration in the database; at worst it could cause external clients accessing data through the xref:ugvro.adoc#[Restful Objects] viewer to break.
+At best this will require a data migration in the database; at worst it could cause external clients accessing data through the xref:../ugvro/ugvro.adoc#[Restful Objects] viewer to break.
 ====
 
 [NOTE]

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-XmlJavaTypeAdapter.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-XmlJavaTypeAdapter.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-XmlJavaTypeAdapter.adoc
index 2b2a034..b24585c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-XmlJavaTypeAdapter.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-XmlJavaTypeAdapter.adoc
@@ -22,6 +22,6 @@ public class ToDoItem ...  {
 
 This annotation therefore allows view models/DTOs to have references to persistent entities; a common idiom.
 
-For a more complete discussion of writing JAXB view models/DTOs, see xref:ugbtb.adoc#_ugbtb_view-models[this topic]
+For a more complete discussion of writing JAXB view models/DTOs, see xref:../ugbtb/ugbtb.adoc#_ugbtb_view-models[this topic]
 in the user guide.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-XmlRootElement.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-XmlRootElement.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-XmlRootElement.adoc
index ac3b58d..220a1fe 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-XmlRootElement.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-XmlRootElement.adoc
@@ -7,7 +7,7 @@
 
 The `@XmlRootElement` annotation provides an alternative way to define a
 xref:rg.adoc#_ugbtb_view-models[view model], in particular one intended to act as a DTO for use within
-xref:ugvro.adoc#[RestfulObjects viewer], or which contains arbitrarily complex state.
+xref:../ugvro/ugvro.adoc#[RestfulObjects viewer], or which contains arbitrarily complex state.
 
 A view model is a non-persisted domain object whose state is converted to/from a string memento.  In the case of a
 JAXB-annotated object this memento is its XML representation.  JAXB generally requires that the root element of the
@@ -18,7 +18,7 @@ xref:../rgant/rgant.adoc#_rgant-ViewModel[`@ViewModel`] annotation, using `@XmlR
 significant advantages:
 
 * the view model can be used as a "canonical" DTO, for example when accessing data using the
-xref:ugvro.adoc#[RestfulObjects viewer] in combination with the
+xref:../ugvro/ugvro.adoc#[RestfulObjects viewer] in combination with the
 xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`]. +
 +
 This provides a stable and
@@ -74,10 +74,10 @@ public class ToDoItemDto implements Dto {
 Although (like any other viewmodel) a JAXB-annotated can have behaviour (actions) and UI hints, you may wish to keep
 the DTO "clean", just focused on specifying the data contract.
 
-Behaviour can therefore be provided using xref:ugbtb.adoc#_ugbtb_decoupling_mixins[mixins] (annotated with
+Behaviour can therefore be provided using xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_mixins[mixins] (annotated with
 xref:../rgant/rgant.adoc#_rgant-Mixin[`@Mixin`]), while xref:../rgcms/rgcms.adoc#_rgcms_classes_uievent[UI events] can be used
 to obtain title, icons and so on.
 
-For a more complete discussion of writing JAXB view models/DTOs, see xref:ugbtb.adoc#_ugbtb_view-models[this topic]
+For a more complete discussion of writing JAXB view models/DTOs, see xref:../ugbtb/ugbtb.adoc#_ugbtb_view-models[this topic]
 in the user guide.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant_aaa_deprecated.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant_aaa_deprecated.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant_aaa_deprecated.adoc
index d04be91..997eb9e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant_aaa_deprecated.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant_aaa_deprecated.adoc
@@ -20,7 +20,7 @@ The annotations listed in the table below are still supported by Apache Isis, bu
 |Purpose
 |Use instead
 |Layer
-|xref:ugvw.adoc#_ugvw_layout_file-based[File-based layout]?
+|xref:../ugvw/ugvw.adoc#_ugvw_layout_file-based[File-based layout]?
 
 |`@ActionOrder`
 |Order of buttons and menu items representing actions.
@@ -99,7 +99,7 @@ The annotations listed in the table below are still supported by Apache Isis, bu
 
 |`@Debug`
 |Action only invokable in debug mode.
-|Not supported by either the xref:ugvw.adoc#[Wicket viewer] or the xref:ugvro.adoc#[RestfulObjects viewer]; use prototype mode instead (xref:../rgant/rgant.adoc#_rgant-Action_restrictTo[`@Action#restrictTo()`])
+|Not supported by either the xref:../ugvw/ugvw.adoc#[Wicket viewer] or the xref:../ugvro/ugvro.adoc#[RestfulObjects viewer]; use prototype mode instead (xref:../rgant/rgant.adoc#_rgant-Action_restrictTo[`@Action#restrictTo()`])
 |UI
 |
 
@@ -117,7 +117,7 @@ The annotations listed in the table below are still supported by Apache Isis, bu
 
 |`@Exploration`
 |Action available in special 'exploration' mode.
-|Not supported by either the xref:ugvw.adoc#[Wicket viewer] or the xref:ugvro.adoc#[RestfulObjects viewer]; use prototype mode instead (xref:../rgant/rgant.adoc#_rgant-Action_restrictTo[`@Action#restrictTo()`])
+|Not supported by either the xref:../ugvw/ugvw.adoc#[Wicket viewer] or the xref:../ugvro/ugvro.adoc#[RestfulObjects viewer]; use prototype mode instead (xref:../rgant/rgant.adoc#_rgant-Action_restrictTo[`@Action#restrictTo()`])
 |UI
 |
 
@@ -170,13 +170,13 @@ Actions can still be invoked.
 
 |`@MemberGroups`
 |Layout of properties and collections of a domain object or view model object.
-|xref:ugvw.adoc#_ugvw_layout_file-based[dynamic `.layout.xml`] files
+|xref:../ugvw/ugvw.adoc#_ugvw_layout_file-based[dynamic `.layout.xml`] files
 |UI
 |Yes
 
 |@MemberGroupLayout`
 |Grouping of properties into groups, and organizing of properties, collections into columns.
-|xref:ugvw.adoc#_ugvw_layout_file-based[dynamic `.layout.xml`] files
+|xref:../ugvw/ugvw.adoc#_ugvw_layout_file-based[dynamic `.layout.xml`] files
 |UI
 |Yes
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant_aaa_jdo.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant_aaa_jdo.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant_aaa_jdo.adoc
index 7c40b21..cab9628 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant_aaa_jdo.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant_aaa_jdo.adoc
@@ -36,7 +36,7 @@ The table below lists the JDO annotations currently recognized by Apache Isis.
 
 |xref:../rgant/rgant.adoc#_rgant-Discriminator[`@javax.jdo.annotations.` +
 `Discriminator`]
-|Override for the object type, as used in `Bookmark`s, URLs for xref:ugvro.adoc#[RestfulObjects viewer] and elsewhere. +
+|Override for the object type, as used in `Bookmark`s, URLs for xref:../ugvro/ugvro.adoc#[RestfulObjects viewer] and elsewhere. +
 
 Note that the discriminator overrides the object type that may otherwise be inferred from the xref:../rgant/rgant.adoc#_rgant-PersistenceCapable[`@PersistenceCapable`] annotation.
 |Domain / persistence
@@ -45,7 +45,7 @@ Note that the discriminator overrides the object type that may otherwise be infe
 
 |xref:../rgant/rgant.adoc#_rgant-NotPersistent[`@javax.jdo.annotations.` +
 `NotPersistent`]
-|Used to determine whether to enforce or skip some xref:ugbtb.adoc#_ugbtb_programming-model_custom-validator[metamodel validation] for `@Column` versus equivalent Isis annotations.
+|Used to determine whether to enforce or skip some xref:../ugbtb/ugbtb.adoc#_ugbtb_programming-model_custom-validator[metamodel validation] for `@Column` versus equivalent Isis annotations.
 
 |Domain / persistence
 |Property
@@ -56,7 +56,7 @@ Note that the discriminator overrides the object type that may otherwise be infe
 `PersistenceCapable`]
 |Used to build Apache Isis' own internal identifier for objects. +
 
-If the `schema()` attribute is specified (and if xref:../rgant/rgant.adoc#_rgant-Discriminator[`@Discriminator`] _hasn't_ been specified), is also used to derive the object type, as used in `Bookmark`s, URLs for xref:ugvro.adoc#[RestfulObjects viewer] and elsewhere.
+If the `schema()` attribute is specified (and if xref:../rgant/rgant.adoc#_rgant-Discriminator[`@Discriminator`] _hasn't_ been specified), is also used to derive the object type, as used in `Bookmark`s, URLs for xref:../ugvro/ugvro.adoc#[RestfulObjects viewer] and elsewhere.
 
 |Domain / persistence
 |Class

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant_aaa_jee.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant_aaa_jee.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant_aaa_jee.adoc
index 5435a7b..6b03cdf 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant_aaa_jee.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant_aaa_jee.adoc
@@ -16,7 +16,7 @@ The table below lists the JEE annotations currently recognized.  Expect to see m
 |Annotation
 |Purpose
 |Layer
-|xref:ugvw.adoc#_ugvw_layout_file-based[File-based layout]?
+|xref:../ugvw/ugvw.adoc#_ugvw_layout_file-based[File-based layout]?
 
 |xref:../rgant/rgant.adoc#_rgant-Digits[`@javax.validation.` +
 `constraints.` +

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant_aaa_main.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant_aaa_main.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant_aaa_main.adoc
index 26e6530..bb06696 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant_aaa_main.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant_aaa_main.adoc
@@ -11,7 +11,7 @@ For each of these domain types and members there are two annotations.  One cover
 
 [TIP]
 ====
-Most UI semantics can also be specified using xref:ugvw.adoc#_ugvw_layout_file-based[dynamic object layout].
+Most UI semantics can also be specified using xref:../ugvw/ugvw.adoc#_ugvw_layout_file-based[dynamic object layout].
 ====
 
 
@@ -24,7 +24,7 @@ The table below summarizes these most commonly used annotations in Apache Isis.
 |Annotation
 |Purpose
 |Layer
-|xref:ugvw.adoc#_ugvw_layout_file-based[File-based layout]?
+|xref:../ugvw/ugvw.adoc#_ugvw_layout_file-based[File-based layout]?
 
 |xref:../rgant/rgant.adoc#_rgant-Action[`@Action`]
 |Domain semantics for actions

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant_aaa_other.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant_aaa_other.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant_aaa_other.adoc
index db3a31a..876fb1b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant_aaa_other.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant_aaa_other.adoc
@@ -13,7 +13,7 @@ These annotations are also commonly used, but relate _not_ to objects or object
 |Annotation
 |Purpose
 |Layer
-|xref:ugvw.adoc#_ugvw_layout_file-based[File-based layout]?
+|xref:../ugvw/ugvw.adoc#_ugvw_layout_file-based[File-based layout]?
 
 |xref:../rgant/rgant.adoc#_rgant-Facets[`@Facets`]
 |Install arbitrary facets within the Apache Isis metamodel.

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgcfg/_rgcfg_configuration-files.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcfg/_rgcfg_configuration-files.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcfg/_rgcfg_configuration-files.adoc
index fb02fbe..ddb9c8b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcfg/_rgcfg_configuration-files.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcfg/_rgcfg_configuration-files.adoc
@@ -11,9 +11,9 @@ The `WEBINF/isis.properties` file is always read and must exist.
 
 In addition, the following other properties are searched for and if present also read:
 
-* `viewer_wicket.properties` - if the xref:ugvw.adoc#[Wicket viewer] is in use
+* `viewer_wicket.properties` - if the xref:../ugvw/ugvw.adoc#[Wicket viewer] is in use
 
-* `viewer_restfulobjects.properties` - if the xref:ugvro.adoc#[RestfulObjects viewer] is in use
+* `viewer_restfulobjects.properties` - if the xref:../ugvro/ugvro.adoc#[RestfulObjects viewer] is in use
 
 * `viewer.properties` - for any other viewer configuration (but there are none currently)
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgcfg/_rgcfg_configuring-core.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcfg/_rgcfg_configuring-core.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcfg/_rgcfg_configuring-core.adoc
index bd72906..c4948a0 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcfg/_rgcfg_configuring-core.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcfg/_rgcfg_configuring-core.adoc
@@ -8,7 +8,7 @@ This section lists the core/runtime configuration properties recognized by Apach
 
 [NOTE]
 ====
-Configuration properties for the JDO/DataNucleus objectstore can be found in the xref:ugodn.adoc#_ugodn_configuring[Configuring DataNucleus] section later in this chapter, while configuration properties for the viewers can be found in the their respective chapters, xref:ugvw.adoc#_ugvw_configuration-properties[here for Wicket viewer], and xref:ugvro.adoc#_ugvro_configuration-properties[here for the Restful Objects viewer].
+Configuration properties for the JDO/DataNucleus objectstore can be found in the xref:../ugodn/ugodn.adoc#_ugodn_configuring[Configuring DataNucleus] section later in this chapter, while configuration properties for the viewers can be found in the their respective chapters, xref:../ugvw/ugvw.adoc#_ugvw_configuration-properties[here for Wicket viewer], and xref:../ugvro/ugvro.adoc#_ugvro_configuration-properties[here for the Restful Objects viewer].
 ====
 
 
@@ -458,7 +458,7 @@ This property is IGNORED if the xref:../rgcfg/rgcfg.adoc#_rgcfg_configuring-comp
 | `read`,`write`
 |Whether to force the `TranslationService` into either read or write mode. +
 
-See xref:ugbtb.adoc#_ugbtb_i18n[i18n support] to learn more about the translation service.
+See xref:../ugbtb/ugbtb.adoc#_ugbtb_i18n[i18n support] to learn more about the translation service.
 
 
 |===
@@ -481,7 +481,7 @@ See xref:ugbtb.adoc#_ugbtb_i18n[i18n support] to learn more about the translatio
 |`FQCN`
 |Custom implementation of `MetaModelValidator` (in the `org.apache.isis.core.metamodel.specloader.validator` package) +
 
-See xref:ugbtb.adoc#_ugbtb_programming-model_custom-validator[Custom Validator] to learn more.
+See xref:../ugbtb/ugbtb.adoc#_ugbtb_programming-model_custom-validator[Custom Validator] to learn more.
 
 |`isis.reflector.validator.` +
 `actionCollection` +
@@ -507,7 +507,7 @@ See also `isis.reflector.facets.ignoreDeprecated`.
 (`false`)
 | Whether to check that the class has an object type explicitly specified somehow.
 
-The object type is used by the framework as an alias for the object's concrete class; it is one part of the object's OID and can be seen in the URLs of the xref:ugvw.adoc#[Wicket viewer] and xref:ugvro.adoc#[Restful Objects viewer], and is encoded in the ``Bookmark``s returned by the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`].
+The object type is used by the framework as an alias for the object's concrete class; it is one part of the object's OID and can be seen in the URLs of the xref:../ugvw/ugvw.adoc#[Wicket viewer] and xref:../ugvro/ugvro.adoc#[Restful Objects viewer], and is encoded in the ``Bookmark``s returned by the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`].
 In this was it may also be persisted, for example in polymorphic associations or command or auditing tables.
 
 If the object type is not specified explicitly, then this can cause data migration issues if the class is subsequently refactored (eg renamed, or moved to a different package).
@@ -547,7 +547,7 @@ This is by way of possibly deprecating and eventually moving contributed service
 | When searching for  xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_disable[`disableXxx()`] or xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_hide[`hideXxx()`] methods, whether to search only for the no-param version (or also for supporting methods that match the parameter types of the action). +
 
 If enabled then will not search for supporting methods with the exact set of arguments as the method it was supporting (and any supporting methods that have additional parameters will be treated as invalid).
-Note that this in effect means that xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins[mixins] must be used instead of xref:ugbtb.adoc#_ugbtb_decoupling_contributions[contributed services].
+Note that this in effect means that xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins[mixins] must be used instead of xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_contributions[contributed services].
 
 
 |`isis.reflector.validator.` +
@@ -620,7 +620,7 @@ See xref:../rgcfg/rgcfg.adoc#__rgcfg_configuring-core_filterVisibility[section b
 |This property is now ignored.  +
 +
 To customize the programming model, use `facets.exclude` and `facets.include`.
-See xref:ugbtb.adoc#_ugbtb_programming-model_finetuning[finetuning the programming model] for more details.
+See xref:../ugbtb/ugbtb.adoc#_ugbtb_programming-model_finetuning[finetuning the programming model] for more details.
 
 
 
@@ -629,7 +629,7 @@ See xref:ugbtb.adoc#_ugbtb_programming-model_finetuning[finetuning the programmi
 |`FQCN`,`FQCN2`,...
 |Fully qualified class names of (existing, built-in) facet factory classes to be included to the programming model. +
 
-See xref:ugbtb.adoc#_ugbtb_programming-model_finetuning[finetuning the programming model] for more details.
+See xref:../ugbtb/ugbtb.adoc#_ugbtb_programming-model_finetuning[finetuning the programming model] for more details.
 
 
 |`isis.reflector.facets.` +
@@ -650,15 +650,15 @@ To be safe, we recommend that you first run your application using `isis.reflect
 `include`
 |`FQCN`,`FQCN2`,...
 |Fully qualified class names of (new, custom) facet factory classes to be included to the programming model. +
-See xref:ugbtb.adoc#_ugbtb_programming-model_finetuning[finetuning the programming model] for more details.
+See xref:../ugbtb/ugbtb.adoc#_ugbtb_programming-model_finetuning[finetuning the programming model] for more details.
 
 
 |`isis.reflector.` +
 `layoutMetadataReaders`
 |`FQCN`,`FQCN2`,...
-|Fully qualified class names of classes to be instantiated to read layout metadata, as used in for xref:ugvw.adoc#_ugvw_layout_file-based[file-based layout]s. +
+|Fully qualified class names of classes to be instantiated to read layout metadata, as used in for xref:../ugvw/ugvw.adoc#_ugvw_layout_file-based[file-based layout]s. +
 
-See xref:ugbtb.adoc#_ugbtb_programming-model_layout-metadata-reader[Layout Metadata Reader] for more information.
+See xref:../ugbtb/ugbtb.adoc#_ugbtb_programming-model_layout-metadata-reader[Layout Metadata Reader] for more information.
 
 
 
@@ -717,7 +717,7 @@ By default this configuration property is enabled.  To disable the visibility fi
 isis.reflector.facet.filterVisibility=false
 ----
 
-Filtering is supported by the xref:ugvw.adoc#[Wicket viewer] and the xref:ugvro.adoc#[Restful Objects viewer], and also by the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`] domain service (provided the wrapper's execution mode is __not__ "skip rules").
+Filtering is supported by the xref:../ugvw/ugvw.adoc#[Wicket viewer] and the xref:../ugvro/ugvro.adoc#[Restful Objects viewer], and also by the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`] domain service (provided the wrapper's execution mode is __not__ "skip rules").
 
 [NOTE]
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgcfg/_rgcfg_deployment-types.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcfg/_rgcfg_deployment-types.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcfg/_rgcfg_deployment-types.adoc
index b29d0f4..42d3c64 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcfg/_rgcfg_deployment-types.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcfg/_rgcfg_deployment-types.adoc
@@ -15,7 +15,7 @@ When running in development/prototyping mode, certain capabilities are enabled;
 
 == Using the Wicket Viewer
 
-Most of the you're likely to run Apache Isis using the xref:ugvw.adoc#[Wicket viewer].  In this case Apache Isis' "deployment type" concept maps to Wicket's "configuration" concept:
+Most of the you're likely to run Apache Isis using the xref:../ugvw/ugvw.adoc#[Wicket viewer].  In this case Apache Isis' "deployment type" concept maps to Wicket's "configuration" concept:
 
 .Apache Isis' deployment type corresponds to Apache Wicket's configuration
 [cols="1,1,2", options="header"]
@@ -64,9 +64,9 @@ Wicket's mechanism for specifying the "configuration" is to use a context parame
 
 == Restful Objects viewer only
 
-Most Apache Isis applications will consist of at least the xref:ugvw.adoc#[Wicket viewer] and optionally the xref:ugvro.adoc#[RestfulObjects viewer].  When both viewers are deployed in the same app, then the bootstrapping is performed by Wicket, and so the deployment type is configured as described in the previous section.
+Most Apache Isis applications will consist of at least the xref:../ugvw/ugvw.adoc#[Wicket viewer] and optionally the xref:../ugvro/ugvro.adoc#[RestfulObjects viewer].  When both viewers are deployed in the same app, then the bootstrapping is performed by Wicket, and so the deployment type is configured as described in the previous section.
 
-In some cases though you may be using Apache Isis to provide a REST API only, that is, you won't have deployed the Wicket viewer.  In these cases your app will be bootstrapped using  Apache Isis' xref:ugbtb.adoc#__ugbtb_web-xml_servlet-context-listeners[ `IsisWebAppBootstrapper`].
+In some cases though you may be using Apache Isis to provide a REST API only, that is, you won't have deployed the Wicket viewer.  In these cases your app will be bootstrapped using  Apache Isis' xref:../ugbtb/ugbtb.adoc#__ugbtb_web-xml_servlet-context-listeners[ `IsisWebAppBootstrapper`].
 
 In this case the deployment type is specified through an Apache Isis-specific context parameter, called `isis.deploymentType`:
 
@@ -96,7 +96,7 @@ In this case the deployment type is specified through an Apache Isis-specific co
 
 == Overriding the deployment type
 
-If bootstrapping the application using Apache Isis' xref:ugbtb.adoc#_ugbtb_deployment_cmd-line[`org.apache.isis.WebServer`] then it is possible to override the deployment type using the `-t` (or `--type`) flag.
+If bootstrapping the application using Apache Isis' xref:../ugbtb/ugbtb.adoc#_ugbtb_deployment_cmd-line[`org.apache.isis.WebServer`] then it is possible to override the deployment type using the `-t` (or `--type`) flag.
 
 For example:
 
@@ -107,5 +107,5 @@ java -jar ... org.apache.isis.WebServer -t SERVER
 
 where "..." is the (usually rather long) list of JAR files and class directories that will make up your application.
 
-This works for both the xref:ugvw.adoc#[Wicket viewer] and the xref:ugvro.adoc#[RestfulObjects viewer].
+This works for both the xref:../ugvw/ugvw.adoc#[Wicket viewer] and the xref:../ugvro/ugvro.adoc#[RestfulObjects viewer].
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgcfg/_rgcfg_specifying-components.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcfg/_rgcfg_specifying-components.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcfg/_rgcfg_specifying-components.adoc
index 00af60a..436702d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcfg/_rgcfg_specifying-components.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcfg/_rgcfg_specifying-components.adoc
@@ -98,7 +98,7 @@ If the `AppManifest` is _not_ being used then there are number of other configur
 
 == Viewer Configuration
 
-Viewers are specified by way of the filters and servlets in the xref:ugbtb.adoc#_ugbtb_web-xml[`web.xml`] file; these are not bootstrapped by the framework, rather it is the other way around.
+Viewers are specified by way of the filters and servlets in the xref:../ugbtb/ugbtb.adoc#_ugbtb_web-xml[`web.xml`] file; these are not bootstrapped by the framework, rather it is the other way around.
 
 In versions prior to `1.13.0`, the "isis.viewers" context parameter was used to hint which configuration files should be read (corresponding to the viewers in use).  As of `1.13.0`, however, the configuration property has no effect: the `viewer_wicket.properties` and `viewer_restulobjects.properties` are always loaded if available.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgcfg/rgcfg.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcfg/rgcfg.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcfg/rgcfg.adoc
index 69d1dea..2cd064c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcfg/rgcfg.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcfg/rgcfg.adoc
@@ -16,15 +16,15 @@ This guide describes how to configure an Apache Isis application.
 [NOTE]
 ====
 This guide covers only the core configuration properties (relating to Apache Isis' metamodel and runtime management).
-Configuration properties for the viewers can be found in the xref:ugvw.adoc#[Wicket Viewer] guide and the xref:ugvro.adoc#[RestfulObjects viewer] guide.
+Configuration properties for the viewers can be found in the xref:../ugvw/ugvw.adoc#[Wicket Viewer] guide and the xref:../ugvro/ugvro.adoc#[RestfulObjects viewer] guide.
 Likewise details of configuring security (Apache Shiro) can be
-found in the xref:ugsec.adoc#[Security] guide, and details for configuring the DataNucleus Object Store can be found in the xref:ugodn.adoc#[DataNucleus] guide.
+found in the xref:../ugsec/ugsec.adoc#[Security] guide, and details for configuring the DataNucleus Object Store can be found in the xref:../ugodn/ugodn.adoc#[DataNucleus] guide.
 ====
 
 [TIP]
 ====
 By default the configuration values are part of the built WAR file.
-Details on how to override these configuration properties externally for different environments can be found in the xref:ugbtb.adoc#_ugbtb_deployment[Beyond the Basics] guide, (deployment chapter).
+Details on how to override these configuration properties externally for different environments can be found in the xref:../ugbtb/ugbtb.adoc#_ugbtb_deployment[Beyond the Basics] guide, (deployment chapter).
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes.adoc
index 213d973..9aa0866 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-This chapter describes the usage of various classes and interfaces that are not otherwise associated with xref:../rgsvc/rgsvc.adoc[domain services], xref:ugvw.adoc#_ugvw_layout[object layout] or xref:../rgcfg/rgcfg.adoc#_rgcfg[configuration].
+This chapter describes the usage of various classes and interfaces that are not otherwise associated with xref:../rgsvc/rgsvc.adoc[domain services], xref:../ugvw/ugvw.adoc#_ugvw_layout[object layout] or xref:../rgcfg/rgcfg.adoc#_rgcfg[configuration].
 
 
 include::_rgcms_classes_AppManifest-bootstrapping.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_AppManifest-bootstrapping.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_AppManifest-bootstrapping.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_AppManifest-bootstrapping.adoc
index d80fd36..b200e09 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_AppManifest-bootstrapping.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_AppManifest-bootstrapping.adoc
@@ -105,7 +105,7 @@ If this method returns a non-`null` value, then it overrides the value of `isis.
 
 If non-`null`, this method specifies the authentication mechanism to use.  The valid values are currently `"shiro"`  or `"bypass"`.  If null is returned then the value of the `isis.authentication` configuration property (in `isis.properties` file) is used instead.
 
-See the xref:ugsec.adoc#[security guide] for further details on configuring shiro or bypass security.
+See the xref:../ugsec/ugsec.adoc#[security guide] for further details on configuring shiro or bypass security.
 
 [NOTE]
 ====
@@ -118,7 +118,7 @@ This property is ignored for integration tests (which always uses the `"bypass"`
 
 If non-`null`, this method specifies the authorization mechanism to use.  The valid values are currently `"shiro"`  or `"bypass"`.  If null is returned then the value of the `isis.authorization` configuration property (in `isis.properties` file) is used instead.
 
-See the xref:ugsec.adoc#[security guide] for further details on configuring shiro or bypass security.
+See the xref:../ugsec/ugsec.adoc#[security guide] for further details on configuring shiro or bypass security.
 
 [NOTE]
 ====
@@ -244,7 +244,7 @@ configuration properties.  This class is still supported, but is deprecated.
 
 === Webapps
 
-To bootstrap an Apache Isis webapp (using the xref:ugvw.adoc#[Wicket viewer]), there are two choices:
+To bootstrap an Apache Isis webapp (using the xref:../ugvw/ugvw.adoc#[Wicket viewer]), there are two choices:
 
 * either specify the `AppManifest` by overriding the `IsisWicketApplication#newWicketModule()`, eg: +
 +
@@ -276,7 +276,7 @@ The first (programmatic) approach takes precedence over the second approach (con
 
 [TIP]
 ====
-If you use the `org.apache.isis.WebServer` class to launch your application from the xref:ugbtb.adoc#_ugbtb_deployment_cmd-line[command line], then note that you can specify the `AppManifest` using the `-m` (or `--manifest`) flag:
+If you use the `org.apache.isis.WebServer` class to launch your application from the xref:../ugbtb/ugbtb.adoc#_ugbtb_deployment_cmd-line[command line], then note that you can specify the `AppManifest` using the `-m` (or `--manifest`) flag:
 
 [source,ini]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_i18n_TranslatableString.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_i18n_TranslatableString.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_i18n_TranslatableString.adoc
index 0c77849..8745506 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_i18n_TranslatableString.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_i18n_TranslatableString.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-IMPORTANT: FIXME - see xref:ugbtb.adoc#_ugbtb_i18n[user guide, i18n].
+IMPORTANT: FIXME - see xref:../ugbtb/ugbtb.adoc#_ugbtb_i18n[user guide, i18n].
 
 The `TranslatableString` utility class ...
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_layout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_layout.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_layout.adoc
index bcd821d..6f860f8 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_layout.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_layout.adoc
@@ -12,7 +12,7 @@ The `org.apache.isis.applib.layout` package defines a number of classes that all
 
 * common component classes, that capture the layout metadata for an object's properties, collections and actions.  These are bound (or associated) to the regions of the grid
 
-The framework provides an implementation of the grid classes modelled closely on link:http://getbootstrap.com[Bootstrap 3], along with xref:ugvw.adoc[Wicket viewer] components capable of rendering that grid system.  In principle it is
+The framework provides an implementation of the grid classes modelled closely on link:http://getbootstrap.com[Bootstrap 3], along with xref:../ugvw/ugvw.adoc[Wicket viewer] components capable of rendering that grid system.  In principle it is
 also possible to extend the layout architecture for other grid systems.  The component classes, though, are intended to be reusable across all grid systems.
 
 The component classes, meanwhile, are broadly equivalent to the "layout" annotations (xref:../rgant/rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`], xref:../rgant/rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`], xref:../rgant/rgant.adoc#_rgant-ActionLayout[`@ActionLayout`] and xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout[`@DomainObjectLayout`]
@@ -89,6 +89,6 @@ responsive designs.
 
 As you can probably guess, the `BS3Grid` is the top-level object (that is, it is JAXB `@XmlRootElement`); this is the object that is serialized to/from XML.
 
-All of these classes also allow custom CSS to be specified; these are added to the CSS classes for the corresponding `<div`> in the rendered page.  The xref:ugvw.adoc#_ugvw_customisation_tweaking-css-classes[`application.css`] file can then be used for application-specific CSS, allowing arbitrary fine-tuning of the layout of the page.
+All of these classes also allow custom CSS to be specified; these are added to the CSS classes for the corresponding `<div`> in the rendered page.  The xref:../ugvw/ugvw.adoc#_ugvw_customisation_tweaking-css-classes[`application.css`] file can then be used for application-specific CSS, allowing arbitrary fine-tuning of the layout of the page.
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_mixins_Dto.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_mixins_Dto.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_mixins_Dto.adoc
index 9c4585a..31e709e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_mixins_Dto.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_mixins_Dto.adoc
@@ -7,7 +7,7 @@
 
 The `Dto` role interface is intended to be implemented by JAXB-annotated view models, that is, annotated using
 xref:../rgant/rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`].  It enables the ability to download the XML and
-XSD schema of those objects using two xref:ugbtb.adoc#_ugbtb_decoupling_mixins[mixins],
+XSD schema of those objects using two xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_mixins[mixins],
 `Dto_downloadXml` and `Dto_downloadXsd`.
 
 The interface is just a marker interface (with no members), and is defined as:

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_mixins_Object.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_mixins_Object.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_mixins_Object.adoc
index ef0b283..db37617 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_mixins_Object.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_mixins_Object.adoc
@@ -14,7 +14,7 @@ The framework provides a single mixin that contributes to simply `java.lang.Obje
 
 When a domain object is rendered the end-user can select different tabs, and for collections can sort the columns,
 navigate to second pages, or select different views of collections.  If the user revisits that object, the
-xref:ugvw.adoc[Wicket viewer] will remember these hints and render the domain object in the same state.  These
+xref:../ugvw/ugvw.adoc[Wicket viewer] will remember these hints and render the domain object in the same state.  These
 rendering hints are also included if the user copies the URL using the anchor link (to right hand of the object's
 title).
 
@@ -47,7 +47,7 @@ each rendered object, per user.
 [[__rgcms_classes_mixins_Object_downloadLayoutXml]]
 == `downloadLayoutXml()`
 
-The `Object_downloadLayoutXml` mixin provides an action to download the xref:ugvw.adoc#_ugvw_layout_file-based[layout XML] for the current domain object.  It has the following signature:
+The `Object_downloadLayoutXml` mixin provides an action to download the xref:../ugvw/ugvw.adoc#_ugvw_layout_file-based[layout XML] for the current domain object.  It has the following signature:
 
 [source,java]
 ----
@@ -60,7 +60,7 @@ public Object downloadLayoutXml(
 ----
 <1> either current, complete, normalized or minimal.
 
-See the documentation on xref:ugvw.adoc#_ugvw_layout_file-based[layout XML] and also
+See the documentation on xref:../ugvw/ugvw.adoc#_ugvw_layout_file-based[layout XML] and also
 the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_LayoutService[`LayoutService`] for more information on these styles
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_super_FixtureScript.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_super_FixtureScript.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_super_FixtureScript.adoc
index 69a16a9..fe29442 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_super_FixtureScript.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_super_FixtureScript.adoc
@@ -17,5 +17,5 @@ protected abstract void execute(final ExecutionContext executionContext);
 In this method the fixture script can in theory do anything, but in practice it is recommended that it uses injected
 domain services to set up data.  The provided `ExecutionContext` is used to invoke child fixture scripts, and alsocan be used to store references to any created objects (so that the calling test can access these objects/so that they are rendered in the view model).
 
-See the see the xref:ugtst.adoc#_ugtst_fixture-scripts[user guide's testing chapter] for further discussion on the use of fixture scripts, in particular xref:ugtst.adoc#_ugtst_fixture-scripts_api-and-usage[fixture scripts' API and usage].
+See the see the xref:../ugtst/ugtst.adoc#_ugtst_fixture-scripts[user guide's testing chapter] for further discussion on the use of fixture scripts, in particular xref:../ugtst/ugtst.adoc#_ugtst_fixture-scripts_api-and-usage[fixture scripts' API and usage].
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_super_FixtureScripts.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_super_FixtureScripts.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_super_FixtureScripts.adoc
index 04a8e60..8bca805 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_super_FixtureScripts.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_super_FixtureScripts.adoc
@@ -9,4 +9,4 @@ This abstract class is intended to allow a domain service that can execute xref:
 However, it has now been deprecated; instead we recommend that the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_FixtureScriptsSpecificationProvider[`FixtureScriptsSpecificationProvider`] service is
 implemented instead.  The framework will then automatically use xref:../rgsvc/rgsvc.adoc#_rgsvc_api_FixtureScriptsDefault[`FixtureScriptsDefault`] as a fallback implementation of this class.
 
-See the see the xref:ugtst.adoc#_ugtst_fixture-scripts[user guide's testing chapter] for further discussion on the use of fixture scripts, in particular xref:ugtst.adoc#_ugtst_fixture-scripts_api-and-usage[fixture scripts' API and usage].
+See the see the xref:../ugtst/ugtst.adoc#_ugtst_fixture-scripts[user guide's testing chapter] for further discussion on the use of fixture scripts, in particular xref:../ugtst/ugtst.adoc#_ugtst_fixture-scripts_api-and-usage[fixture scripts' API and usage].

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes.adoc
index 25cde24..f63cab2 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes.adoc
@@ -44,7 +44,7 @@ Param
 
 [NOTE]
 ====
-Directly mutable collections are not currently supported by the xref:ugvw.adoc#[Wicket viewer].
+Directly mutable collections are not currently supported by the xref:../ugvw/ugvw.adoc#[Wicket viewer].
 ====
 
 See also xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_removeFrom[`removeFrom...()`]`
@@ -142,7 +142,7 @@ See also xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_clear[`clear...()`]`.
 
 [NOTE]
 ====
-Directly mutable collections are not currently supported by the xref:ugvw.adoc#[Wicket viewer].
+Directly mutable collections are not currently supported by the xref:../ugvw/ugvw.adoc#[Wicket viewer].
 ====
 
 See also xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_addTo[`addTo...()`]`
@@ -177,7 +177,7 @@ AddTo...()`]
 
 [NOTE]
 ====
-Directly mutable collections are not currently supported by the xref:ugvw.adoc#[Wicket viewer].
+Directly mutable collections are not currently supported by the xref:../ugvw/ugvw.adoc#[Wicket viewer].
 ====
 
 See also xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_validateRemoveFrom[`validateRemoveFrom...()`], and xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_validate[`validate...()`] for properties and actions.
@@ -193,7 +193,7 @@ RemoveFrom...()`]
 
 [NOTE]
 ====
-Directly mutable collections are not currently supported by the xref:ugvw.adoc#[Wicket viewer].
+Directly mutable collections are not currently supported by the xref:../ugvw/ugvw.adoc#[Wicket viewer].
 ====
 
 See also xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_validateAddTo[`validateAddTo...()`], and xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_validate[`validate...()`] for properties and actions.

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_addTo.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_addTo.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_addTo.adoc
index 5ab34de..ba67ff6 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_addTo.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_addTo.adoc
@@ -11,7 +11,7 @@ The `addTo...()` supporting method is called whenever an object is added to a co
 
 [NOTE]
 ====
-Directly mutable collections are not currently supported by the xref:ugvw.adoc#[Wicket viewer].  The suggested workaround is to simply define an action.
+Directly mutable collections are not currently supported by the xref:../ugvw/ugvw.adoc#[Wicket viewer].  The suggested workaround is to simply define an action.
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_disable.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_disable.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_disable.adoc
index 16ca889..b4e4e86 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_disable.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_disable.adoc
@@ -12,14 +12,14 @@ It allows the modification of the property/collection to be vetoed (ie made read
 
 [NOTE]
 ====
-Directly mutable collections are not currently supported by the xref:ugvw.adoc#[Wicket viewer]; they are always implicitly disabled.
+Directly mutable collections are not currently supported by the xref:../ugvw/ugvw.adoc#[Wicket viewer]; they are always implicitly disabled.
 ====
 
 Typically modification/invocation is vetoed based on the state of the domain object being interacted with, though it could be any reason at all (eg the current date/time of the interaction, or the state of some other related data such as stock levels, or the identity of the calling user).
 
 
 The reason for vetoing a modification/invocation is normally returned as a string.
-However, Apache Isis' xref:ugbtb.adoc#_ugbtb_i18n[i18n support] extends this so that reasons can be internationalized.
+However, Apache Isis' xref:../ugbtb/ugbtb.adoc#_ugbtb_i18n[i18n support] extends this so that reasons can be internationalized.
 
 
 
@@ -89,6 +89,6 @@ public class Customer {
 In the case of actions, the framework will also search for supporting method that has the exact same parameter types as the action itself.
 Enabling `isis.reflector.validator.noParamsOnly` configuration property switches this off, so that the framework will only search for supporting method with no parameters.
 
-Note that enabling this configuration property in effect means that xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins[mixins] must be used instead of xref:ugbtb.adoc#_ugbtb_decoupling_contributions[contributed services] (because contributed actions are the one case where the value of a parameter to a supporting method may be non-null).
+Note that enabling this configuration property in effect means that xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins[mixins] must be used instead of xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_contributions[contributed services] (because contributed actions are the one case where the value of a parameter to a supporting method may be non-null).
 ====
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_hide.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_hide.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_hide.adoc
index 7566041..7c90d4b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_hide.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_hide.adoc
@@ -65,6 +65,6 @@ public class Customer {
 In the case of actions, the framework will also search for supporting method that has the exact same parameter types as the action itself.
 Enabling `isis.reflector.validator.noParamsOnly` configuration property switches this off, so that the framework will only search for supporting method with no parameters.
 
-Note that enabling this configuration property in effect means that xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins[mixins] must be used instead of xref:ugbtb.adoc#_ugbtb_decoupling_contributions[contributed services] (because contributed actions are the one case where the value of a parameter to a supporting method may be non-null).
+Note that enabling this configuration property in effect means that xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins[mixins] must be used instead of xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_contributions[contributed services] (because contributed actions are the one case where the value of a parameter to a supporting method may be non-null).
 ====
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_removeFrom.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_removeFrom.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_removeFrom.adoc
index e7e07fa..a95aa44 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_removeFrom.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_removeFrom.adoc
@@ -11,7 +11,7 @@ The `removeFrom...()` supporting method is called whenever an object is removed
 
 [NOTE]
 ====
-Directly mutable collections are not currently supported by the xref:ugvw.adoc#[Wicket viewer].  The suggested workaround is to simply define an action.
+Directly mutable collections are not currently supported by the xref:../ugvw/ugvw.adoc#[Wicket viewer].  The suggested workaround is to simply define an action.
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_validate.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_validate.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_validate.adoc
index 4bf3c75..7f3587d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_validate.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_validate.adoc
@@ -11,7 +11,7 @@ It allows the proposed new value for a property to be rejected, or the proposed
 
 
 The reason for vetoing a modification/invocation is normally returned as a string.
-However, Apache Isis' xref:ugbtb.adoc#_ugbtb_i18n[i18n support] extends this so that reasons can be internationalized if required.
+However, Apache Isis' xref:../ugbtb/ugbtb.adoc#_ugbtb_i18n[i18n support] extends this so that reasons can be internationalized if required.
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_validateAddTo.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_validateAddTo.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_validateAddTo.adoc
index afb2550..50e11ec 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_validateAddTo.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_validateAddTo.adoc
@@ -11,7 +11,7 @@ The `validateAddTo...()` supporting method is called whenever an object is to be
 
 [NOTE]
 ====
-Directly mutable collections are not currently supported by the xref:ugvw.adoc#[Wicket viewer].  The suggested workaround is to simply define an action.
+Directly mutable collections are not currently supported by the xref:../ugvw/ugvw.adoc#[Wicket viewer].  The suggested workaround is to simply define an action.
 ====
 
 
@@ -22,7 +22,7 @@ The signature of the supporting method for a collection with element type `E` is
 public String validateAddToXxx(E element) { ... }
 ----
 
-where the returned string is the reason the collection modification invocation is vetoed (or `null` if not vetoed).  Apache Isis' xref:ugbtb.adoc#_ugbtb_i18n[i18n support] extends this so that reasons can be internationalized if required.
+where the returned string is the reason the collection modification invocation is vetoed (or `null` if not vetoed).  Apache Isis' xref:../ugbtb/ugbtb.adoc#_ugbtb_i18n[i18n support] extends this so that reasons can be internationalized if required.
 
 
 For example:

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_validateRemoveFrom.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_validateRemoveFrom.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_validateRemoveFrom.adoc
index acbd98e..cec48a7 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_validateRemoveFrom.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_validateRemoveFrom.adoc
@@ -11,7 +11,7 @@ The `validateRemoveFrom...()` supporting method is called whenever an object is
 
 [NOTE]
 ====
-Directly mutable collections are not currently supported by the xref:ugvw.adoc#[Wicket viewer].  The suggested workaround is to simply define an action.
+Directly mutable collections are not currently supported by the xref:../ugvw/ugvw.adoc#[Wicket viewer].  The suggested workaround is to simply define an action.
 ====
 
 
@@ -22,7 +22,7 @@ The signature of the supporting method for a collection with element type `E` is
 public String validateRemoveFromXxx(E element) { ... }
 ----
 
-where the returned string is the reason the collection modification invocation is vetoed (or `null` if not vetoed).  Apache Isis' xref:ugbtb.adoc#_ugbtb_i18n[i18n support] extends this so that reasons can be internationalized if required.
+where the returned string is the reason the collection modification invocation is vetoed (or `null` if not vetoed).  Apache Isis' xref:../ugbtb/ugbtb.adoc#_ugbtb_i18n[i18n support] extends this so that reasons can be internationalized if required.
 
 
 For example:

[34/58] [abbrv] isis git commit: object titles and icons; fixing links

[da...@apache.org]

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_jaxb.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_jaxb.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_jaxb.adoc
index 8eadadb..ce821b8 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_jaxb.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_jaxb.adoc
@@ -1,10 +1,68 @@
 [[_ugfun_programming-model_view-models_jaxb]]
 = JAXB View Models
-
 :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/
 
 
+Here's a typical example of a JAXB view model, to allow (certain properties of) two ``Customer``s to be compared:
+
+[source,java]
+----
+@XmlRootElement(name = "compareCustomers")          // <1>
+@XmlType(
+        propOrder = {                               // <2>
+            "customer1",
+            "customer2"
+        }
+)
+@XmlAccessorType(XmlAccessType.FIELD)               // <3>
+public class CompareCustomers {
+
+    @XmlElement(required = true)                    // <4>
+    @Getter @Setter
+    Customer customer1;
+
+    @XmlElement(required = true)                    // <4>
+    @Getter @Setter
+    Customer customer2;
+
+    @XmlTransient                                   // <5>
+    public String getCustomer1Name() {
+        return getCustomer1().getName();
+    }
+
+    @XmlTransient                                   // <5>
+    public String getCustomer1Address() {
+        return getCustomer1().getAddress();
+    }
+
+    ...
+}
+----
+<1> The JAXB `@XmlRootElement` annotation indicates this is a view model to Apache Isis, which then uses JAXB to serialize the state of the view model between interactions
+<2> All properties of the view model must be listed using the `XmlType#propOrder` attribute.
+<3> Specifying field accessor type allows the Lombok `@Getter` and `@Setter` annotations to be used.
+<4> The `XmlElement` indicates the property is part of the view model's state.
+For collections, the `@XmlElementWrapper` would also typically be used.
+<5> The `@XmlTransient` indicates that the property is derived and should be ignored by JAXB.
+
+Use JAXB elements such as `@XmlElement` for properties and the combination of `@XmlElementWrapper` and `@XmlElement` for collections.
+Properties can be ignored (for serialization) using `@XmlTransient`.
+
+The derived properties could also have been implemented using xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_types-of-domain-objects_mixins[mixins].
+
+
+[IMPORTANT]
+====
+Be aware that all the state will become the DTO's memento, ultimately converted into a URL-safe form, by way of the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UrlEncodingService[`UrlEncodingService`].
+
+There are limits to the lengths of URLs, however.
+If the URL does exceed limits or contains invalid characters, then provide a custom implementation of xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UrlEncodingService[`UrlEncodingService`] to handle the memento string in some other fashion (eg substituting it with a GUID, with the memento cached somehow on the server).
+a URL.
+====
+
+
+include::_ugfun_programming-model_view-models_jaxb_referencing-domain-entities.adoc[leveloffset=+1]
+
 
-NOTE: FIXME

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_jaxb_referencing-domain-entities.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_jaxb_referencing-domain-entities.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_jaxb_referencing-domain-entities.adoc
new file mode 100644
index 0000000..1808921
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_jaxb_referencing-domain-entities.adoc
@@ -0,0 +1,65 @@
+[[_ugfun_programming-model_view-models_jaxb_referencing-domain-entities]]
+= Referencing Domain Entities
+
+: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/
+
+
+It's quite common for view models to be "backed by" (be projections of) some underlying domain entity.
+For example, the `CompareCustomers` view model described above actually references two underlying ``Customer`` entities.
+
+It wouldn't make sense to serialize out the state of a persistent entity (even more so when the view model is also being used as a DTO).
+However, the identity of the underlying entity can be well defined; Apache Isis defines the xref:../rgcms/rgcms.adoc#_rgcms_schema-common[common schema] which defines the `<oid-dto>` element (and corresponding `OidDto` class): the object's type and its identifier.
+This is basically a formal XML equivalent to the `Bookmark` object obtained from the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`].
+
+There is only one requirement to make this work: every referenced domain entity must be annotated with xref:../rgant/rgant.adoc#_rgant-XmlJavaTypeAdapter[`@XmlJavaTypeAdapter`], specifying the framework-provided `PersistentEntityAdapter.class`.
+And this class is similar to the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`]: it knows how to create an `OidDto` from an object reference.
+
+Thus, in our view model we can legitimately write:
+
+[source,java]
+----
+public class CompareCustomers {
+
+    @XmlElement(required = true)
+    @Getter @Setter
+    Customer customer1;
+    ...
+}
+----
+
+All we need to do is remember to add that `@XmlJavaTypeAdapter` annotation to the referenced entity:
+
+[source,java]
+----
+@XmlJavaTypeAdapter(PersistentEntityAdapter.class)
+public class Customer ...  {
+    ...
+}
+----
+
+
+It's also possible for a DTO view models to hold collections of objects.
+These can be of any type, either simple properties, or references to other objects.
+The only bit of boilerplate that is required is the `@XmlElementWrapper` annotation.
+This instructs JAXB to create an XML element (based on the field name) to contain each of the elements.
+(If this is omitted then the contents of the collection are at the same level as the properties; almost certainly not what is required).
+
+For example, we could perhaps generalize the view model to hold a set of ``Customer``s to be compared:
+
+[source,java]
+----
+public class CompareCustomers {
+    ...
+    @XmlElementWrapper
+    @XmlElement(name = "customers")
+    @Getter @Setter
+    protected List<Customer> customersToCompare = Lists.newArrayList();
+}
+----
+
+This capability is particularly useful when the JAXB view model is being used as a xref:../ugfun/ugfun.adoc#_ugfun_programming-model_view-models_dto[DTO].
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_non-jaxb.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_non-jaxb.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_non-jaxb.adoc
index 2069a9a..92c04ea 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_non-jaxb.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_non-jaxb.adoc
@@ -6,7 +6,74 @@
 :_imagesdir: images/
 
 
+Instead of using JAXB to specify a view model, it is also possible to use Apache Isis-specific annotations.
+
+[WARNING]
+====
+As was explained xref:../ugfun/ugfun.adoc#_ugfun_programming-model_view-models[earlier], the approach is described here is neither as flexible nor as powerful as using the JAXB-style of view models.
+As such, it may be deprecated in the future.
+====
+
+While the underlying technique is the same irrespective of use case, the programming model provides various ways of defining a view model so that the original intent is not lost.
+They are:
+
+.View model programming model
+[cols="1a,4a,2a", options="header"]
+|===
+
+| Use case
+| Code
+| Description
+
+
+| External entity
+|[source,java]
+----
+@DomainObject(nature=Nature.EXTERNAL_ENTITY)
+public class CustomerRecordOnSAP { ... }
+----
+|Annotated with xref:../rgant/rgant.adoc#_rgant-DomainObject_nature[`@DomainObject#nature()`] and a nature of `EXTERNAL_ENTITY`, with memento derived automatically from the properties of the domain object.  Collections are ignored, as are any properties annotated as xref:../rgant/rgant.adoc#_rgant-Property_notPersisted[not persisted].
+
+| In-memory entity
+|[source,java]
+----
+@DomainObject(nature=Nature.INMEMORY_ENTITY)
+public class Log4JAppender { ... }
+----
+|As preceding, but using a nature of `INMEMORY_ENTITY`.
+
+|Application view model
+|[source,java]
+----
+@DomainObject(nature=Nature.VIEW_MODEL)
+public class Dashboard { ... }
+----
+|As preceding, but using a nature of `VIEW_MODEL`.
+
+|Application view model
+|
+[source,java]
+----
+@ViewModel
+public class Dashboard { ... }
+----
+
+|Annotated with xref:../rgant/rgant.adoc#_rgant-ViewModel[`@ViewModel`] annotation (effectively just an alias)' memento is as preceding: from "persisted" properties, collections ignored
+
+|Application view model
+|
+[source,java]
+----
+public class ExcelUploadManager implements ViewModel {
+  public String viewModelMemento() { ... }
+  public void viewModelInit(String memento) { ... }
+}
+|Implement xref:../rgcms/rgcms.adoc#_rgcms_classes_super_ViewModel[`ViewModel`] interface.  The memento is as defined by the
+interface's methods: the programmer has full control (but also full responsibility) for the string memento.
+
+|===
+
+
 
 
-NOTE: FIXME
 

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_object-titles-and-icons.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_object-titles-and-icons.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_object-titles-and-icons.adoc
index a1a3301..fe0d4f6 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_object-titles-and-icons.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_object-titles-and-icons.adoc
@@ -78,26 +78,264 @@ Titles can sometimes get be long and therefore rather cumbersome in "parented" t
 
 === Imperative style
 
-NOTE: FIXME - see xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_title[`title()`]
+Alternatively, the title can be provided simply by implementing the xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_title[`title()`] reserved method.
 
+For example:
+
+[source,java]
+----
+public class Author extends Customer {
+
+    public String title() {
+        StringBuilder buf = new StringBuilder();
+        buf.append(getFirstName());
+        if(getMiddleInitial() != null) {
+            buf.append(getMiddleInitial()).append(". ");
+        }
+        buf.append(getLastName();
+        return buf.toString();
+    }
+    ...
+}
+----
+
+A variation on this approach also supports localized names; see xref:../ugbtb/ugbtb.adoc#_ugbtb_i18n[beyond-the-basics] guide for further details.
+
+
+=== Using a UI subscriber
+
+A third alternative is to move the responsibility for deriving the title into a separate subscriber object.
+
+In the target object, we define an appropriate event type and use the xref:../rgant/rgant.adoc#_rgant_DomainObjectLayout_titleUiEvent[`@DomainObjectLayout#titleUiEvent()`] attribute to specify:
+
+[source,java]
+----
+@DomainObjectLayout(
+    titleUiEvent = Author.TitleUiEvent.class
+)
+public class Author extends Customer {
+    public static class TitleUiEvent
+            extends org.apache.isis.applib.services.eventbus.TitleUiEvent<Author> {}
+    ...
+}
+----
 
+The subscriber can then populate this event:
 
-NOTE: FIXME -
-For more details on the actual UI event classes, see the xref:../rgcms/rgcms.adoc#_rgcms_classes_uievent[UI event] section of the relevant reference guide.
+[source,java]
+----
+@DomainService(nature=NatureOfService.DOMAIN)
+public class AuthorSubscriptions extends AbstractSubscriber {
+
+    @org.axonframework.eventhandling.annotation.EventHandler
+    @com.google.common.eventbus.Subscribe
+    public void on(Author.TitleUiEvent ev) {
+        Author author = ev.getSource();
+        ev.setTitle(titleOf(author);
+    }
+
+    private String titleOf(Author author) {
+        StringBuilder buf = new StringBuilder();
+        buf.append(author.getFirstName());
+        if(author.getMiddleInitial() != null) {
+            buf.append(author.getMiddleInitial()).append(". ");
+        }
+        buf.append(author.getLastName();
+        return buf.toString();
+    }
+}
+----
 
 
 == Object Icon
 
-The icon is often the same for all instances of a particular class, but it's also possible for an individual instance to return a custom icon.  This could represent the state of that object (eg a shipped order, say, or overdue library book).
+The icon is often the same for all instances of a particular class, and is picked up by convention.
 
-NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`], xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_cssClassFa[`@DomainObjectLayout#cssClassFa()`]
+It's is also possible for an individual instance to return a custom icon, typically so that some significant state of that domain object is represented.
+For example, a custom icon could be used to represent a shipped order, say, or an overdue library loan.
 
 
+=== Declarative style
+
+If there is no requirement to customize the icon (the normal case), then the icon is usually picked up as the `.png` file in the same package as the class.
+For example, the icon for a class `org.mydomain.myapp.Customer` will be `org/mydomain/myapp/Customer.png` (if it exists).
+
+Alternatively, font-awesome icon can be used.
+This is specified using the xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_cssClassFa[`@DomainObjectLayout#cssClassFa()`] attribute.
+
+For example:
+
+[source,java]
+----
+@DomainObjectLayout(
+    cssClassFa="play"               // <1>
+)
+public class InvoiceRun {
+    ...
+}
+----
+<1> will use the "fa-play" icon.
+
+
+
+=== Imperative style
+
+To customise the icon on an instance-by-instance basis, we implement the reserved xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_iconName[`iconName()`] method.
+
+For example:
+
+[source,java]
+----
+public class Order {
+    public String iconName() {
+        return isShipped() ? "shipped": null;
+    }
+    ...
+}
+----
+
+In this case, if the `Order` has shipped then the framework will look for an icon image named "Order-shipped.png" (in the same package as the class).
+Otherwise it will just use "Order.png", as normal.
+
+
+
+=== Using a UI subscriber
+
+As for title, the determination of which image file to use for the icon can be externalized into a UI event subscriber.
+
+In the target object, we define an appropriate event type and use the xref:../rgant/rgant.adoc#_rgant_DomainObjectLayout_iconUiEvent[`@DomainObjectLayout#iconUiEvent()`] attribute to specify.
+
+For example
+
+[source,java]
+----
+@DomainObjectLayout(
+    iconUiEvent = Author.IconUiEvent.class
+)
+public class Order {
+    public static class IconUiEvent
+            extends org.apache.isis.applib.services.eventbus.IconUiEvent<Order> {}
+    ...
+}
+----
+
+The subscriber can then populate this event:
+
+[source,java]
+----
+@DomainService(nature=NatureOfService.DOMAIN)
+public class OrderSubscriptions extends AbstractSubscriber {
+
+    @org.axonframework.eventhandling.annotation.EventHandler
+    @com.google.common.eventbus.Subscribe
+    public void on(Order.IconUiEvent ev) {
+        Order order = ev.getSource();
+        ev.setIconName(iconNameOf(order);
+    }
+
+    private String iconNameOf(Order order) {
+        StringBuilder buf = new StringBuilder();
+        return order.isShipped() ? "shipped": null;
+    }
+}
+----
+
 
 
 == Object CSS Styling
 
+It is also possible for an object to return a xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_cssClass[CSS class].
+In conjunction with xref:../ugvw/ugvw.adoc#_ugvw_customisation_tweaking-css-classes[customized CSS] this can be used to apply arbitrary styling; for example each object could be rendered in a page with a different background colour.
+
+In fact, it is also possible to specify additional CSS for an object's members.
+
+
+=== Declarative style
+
+To render an object with a particular CSS, use
+xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_cssClass[`@DomainObjectLayout#cssClass()`].
+
+When the domain object is rendered on its own page, this CSS class will appear on a top-level `<div>`.
+Or, when the domain object is rendered as a row in a collection, then the CSS class will appear in a `<div>` wrapped by the `<tr>` of the row.
+
+One possible use case would be to render the most important object types with a subtle background colour: ``Customer``s shown in light green, or ``Order``s shown in a light pink, for example.
+
+
+Similarly, a CSS class can be specified for object members:
+
+* xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout#cssClass()`] for actions
+
+* xref:../rgant/rgant.adoc#_rgant-PropertyLayout_cssClass[`@PropertyLayout#cssClass()`] for properties, and
+
+* xref:../rgant/rgant.adoc#_rgant-CollectionLayout_cssClass[`@CollectionLayout#cssClass()`] for collections.
+
+Again, this CSS class will be attached to an appropriate containing `<div>` or `<span>` on the rendered page.
+
+Possible use cases for this is to highlight the most important properties of a domain object.
+
+
+=== Imperative style
+
+
+To customise the icon on an instance-by-instance basis, we implement the reserved xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_cssClass[`cssClass()`] method.
+
+For example:
+
+[source,java]
+----
+public class Order {
+    public String cssClass() {
+        return isShipped() ? "shipped": null;       <1>
+    }
+    ...
+}
+----
+<1> the implementation might well be the same as the `iconName()`.
+
+If non-null value is returned then the CSS class will be rendered _in addition_ to any declarative CSS class also specified.
+
+
+=== Using a UI subscriber
+
+
+As for title and icon, the determination of which CSS class to render can be externalized into a UI event subscriber.
+
+In the target object, we define an appropriate event type and use the xref:../rgant/rgant.adoc#_rgant_DomainObjectLayout_cssClassUiEvent[`@DomainObjectLayout#cssClassUiEvent()`] attribute to specify.
+
+For example
+
+[source,java]
+----
+@DomainObjectLayout(
+    cssClassUiEvent = Author.CssClassUiEvent.class
+)
+public class Order {
+    public static class CssClassUiEvent
+            extends org.apache.isis.applib.services.eventbus.CssClassUiEvent<Order> {}
+    ...
+}
+----
+
+The subscriber can then populate this event:
+
+[source,java]
+----
+@DomainService(nature=NatureOfService.DOMAIN)
+public class OrderSubscriptions extends AbstractSubscriber {
+
+    @org.axonframework.eventhandling.annotation.EventHandler
+    @com.google.common.eventbus.Subscribe
+    public void on(Order.CssClassUiEvent ev) {
+        Order order = ev.getSource();
+        ev.setIconName(iconNameOf(order);
+    }
+
+    private String cssClassOf(Order order) {
+        StringBuilder buf = new StringBuilder();
+        return order.isShipped() ? "shipped": null;
+    }
+}
+----
+
 
-It is also possible for an object to return a xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_cssClass[CSS class].  In conjunction with xref:../ugvw/ugvw.adoc#_ugvw_customisation_tweaking-css-classes[customized CSS] this can be used to apply arbitrary styling; for example each object could be rendered in a page with a different background colour.
 
-NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_cssClass[`cssClass()`], xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_cssClass[`@DomainObjectLayout#cssClass()`] xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClass[`@ActionLayout#cssClass()`], xref:../rgant/rgant.adoc#_rgant-PropertyLayout_cssClass[`@PropertyLayout#cssClass()`], xref:../rgant/rgant.adoc#_rgant-CollectionLayout_cssClass[`@CollectionLayout#cssClass()`]

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_overriding-jdo-annotations.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_overriding-jdo-annotations.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_overriding-jdo-annotations.adoc
index 6fead2e..015e8ca 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_overriding-jdo-annotations.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_overriding-jdo-annotations.adoc
@@ -56,7 +56,7 @@ For example, in writing up the above example we found that writing `schema=&quot
 
 * Forcing the schema to "PUBLIC" (as in the above example) works, but it isn't ideal because the name "PUBLIC" is not vendor-neutral (it works for HSQLDB, but MS SQL Server uses "dbo" as its default).
 
-* As of 1.9.0 Apache Isis will automatically (attempt) to create the owning schema for a given table if it does not exist. This behaviour can be customized, as described in the section on xref:_ugbtb_decoupling_db-schemas[using modules].
+* As of 1.9.0 Apache Isis will automatically (attempt) to create the owning schema for a given table if it does not exist. This behaviour can be customized, as described in the section on xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_db-schemas[using modules].
 
 * You may need to override the entire class metadata rather than individual elements; the mixin mentioned above can help here.
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_usage-by-isis-viewers.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_usage-by-isis-viewers.adoc b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_usage-by-isis-viewers.adoc
index f6a8fa4..8ccc349 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_usage-by-isis-viewers.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_usage-by-isis-viewers.adoc
@@ -49,7 +49,9 @@ Similarly, for those object members that _are_ visible, the viewer also checks i
 
 === User-registration
 
-As well as providing a sign-in screen, the Wicket viewer also provides the ability for xref:_user_registration[users to self-register].  By and large this operates outside of Apache Isis' security mechanisms; indeed the various pages (sign-up, sign-up verification, password reset) are all rendered _without_ there being any current user session.  These pages all "reach inside" Apache Isis framework using a mechanism similar to xref:../ugbtb/ugbtb.adoc#_ugbtb_headless-access[Headless access] in order to actually do their stuff.
+As well as providing a sign-in screen, the Wicket viewer also provides the ability for users to self-register.
+By and large this operates outside of Apache Isis' security mechanisms; indeed the various pages (sign-up, sign-up verification, password reset) are all rendered _without_ there being any current user session.
+These pages all "reach inside" Apache Isis framework using a mechanism similar to xref:../ugbtb/ugbtb.adoc#_ugbtb_headless-access[Headless access] in order to actually do their stuff.
 
 [TIP]
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_configuration-properties_suppressing-password-reset.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_configuration-properties_suppressing-password-reset.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_configuration-properties_suppressing-password-reset.adoc
index daf1226..22980dd 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_configuration-properties_suppressing-password-reset.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_configuration-properties_suppressing-password-reset.adoc
@@ -6,7 +6,7 @@
 
 
 
-If xref:_user_registration[user registration] has been configured, then the Wicket viewer allows the user to sign-up a new account and to reset their password from the login page.
+If user registration has been configured, then the Wicket viewer allows the user to sign-up a new account and to reset their password from the login page.
 
 The 'password reset' link can be suppressed, if required, by setting a configuration flag.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_configuration-properties_suppressing-sign-up.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_configuration-properties_suppressing-sign-up.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_configuration-properties_suppressing-sign-up.adoc
index 6d20fea..de3bcde 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_configuration-properties_suppressing-sign-up.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_configuration-properties_suppressing-sign-up.adoc
@@ -8,7 +8,7 @@
 
 
 
-If xref:_user_registration[user registration] has been configured, then the Wicket viewer allows the user to sign-up a new account and to reset their password from the login page.
+If user registration has been configured, then the Wicket viewer allows the user to sign-up a new account and to reset their password from the login page.
 
 The 'sign up' link can be suppressed, if required, by setting a configuration flag.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_file-based.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_file-based.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_file-based.adoc
index 5676d55..9f99703 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_file-based.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_file-based.adoc
@@ -39,7 +39,7 @@ The layout file distinguishes between two types of element:
 
 * those that define a grid structure, of: rows, columns, tab groups and tabs. +
 +
-The rows and columns are closely modelled on link:getbootstrap.com[Bootstrap 3] (used in the implementation of the xref:../ugvw/ugvw.adoc[Wicket viewer]).
+The rows and columns are closely modelled on link:getbootstrap.com[Bootstrap 3] (used in the implementation of the xref:../ugvw/ugvw.adoc#[Wicket viewer]).
 
 * those that defines common components, of: fieldsets (previously called member groups or property groups), properties, collections, actions and also the title/icon of the domain object itself.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.11.0-to-1.12.0.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.11.0-to-1.12.0.adoc b/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.11.0-to-1.12.0.adoc
index 261314a..c4d42a4 100644
--- a/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.11.0-to-1.12.0.adoc
+++ b/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.11.0-to-1.12.0.adoc
@@ -52,7 +52,7 @@ domain object is a view model rather than an entity (that is, has no id or versi
 as top-level actions.
 
 Most of these mixin object members are visible only in prototype mode, though some are visible in production mode and
-so potentially visible to end-users.  If you wish to suppress these members from the view, you can either use xref:guides/ugsec.adoc[security],
+so potentially visible to end-users.  If you wish to suppress these members from the view, you can either use xref:guides/ugsec.adoc#[security],
 or alternatively you can write xref:guides/rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscriber]s to veto the visibility
 of these members by subscribing to their respective domain events.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.12.0-to-1.13.0.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.12.0-to-1.13.0.adoc b/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.12.0-to-1.13.0.adoc
index df56f20..55853a2 100644
--- a/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.12.0-to-1.13.0.adoc
+++ b/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.12.0-to-1.13.0.adoc
@@ -70,7 +70,7 @@ the attribute is not set explicitly.
 Conversely, neither the xref:guides/rgant.adoc#_rgant_Action_publishingPayloadFactory[`@Action#publishingPayloadFactory()`]
 nor the xref:guides/rgant.adoc#_rgant_DomainObject_publishingPayloadFactory[`@DomainObject#publishingPayloadFactory()`] are
 supported by `PublisherService`; instead the consumers of the events are expected to callback for any additional
-information, eg using xref:guides/ugvro.adoc[Resful Objects] viewer.
+information, eg using xref:guides/ugvro.adoc#[Resful Objects] viewer.
 
 
 == Auto-logout

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.9.0-to-1.10.0.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.9.0-to-1.10.0.adoc b/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.9.0-to-1.10.0.adoc
index a9475aa..57f2e3d 100644
--- a/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.9.0-to-1.10.0.adoc
+++ b/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.9.0-to-1.10.0.adoc
@@ -130,7 +130,6 @@ public class ToDoItem {
 
 == isis-maven-plugin
 
-The way that the Isis Maven plugin is configured has changed slightly; check out its
-xref:guides/rgmvn.adoc[documentation] for full details.
+The way that the Isis Maven plugin is configured has changed slightly; check out its xref:guides/rgmvn.adoc#[documentation] for full details.
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/pages/screencasts/screencasts.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/pages/screencasts/screencasts.adoc b/adocs/documentation/src/main/asciidoc/pages/screencasts/screencasts.adoc
index ddcb3c8..b8cb5d5 100644
--- a/adocs/documentation/src/main/asciidoc/pages/screencasts/screencasts.adoc
+++ b/adocs/documentation/src/main/asciidoc/pages/screencasts/screencasts.adoc
@@ -116,7 +116,7 @@ Using the Swagger UI to access the xref:guides/ugvro.adoc#[REST API] automatical
 
 
 |link:https://www.youtube.com/watch?v=yOh3WphhR1E[010^] +
-Using the xref:guides/rgmvn.adoc[Apache Isis maven plugin] to validate domain object models during the build process (rather than at runtime).
+Using the xref:guides/rgmvn.adoc#[Apache Isis maven plugin] to validate domain object models during the build process (rather than at runtime).
 ||||||||x|||
 
 
@@ -213,20 +213,20 @@ Using xref:guides/ugvw.adoc#_ugvw_layout_file-based[dynamic (XML) layouts] to sp
 include::_screencasts-playlists.adoc[]
 
 |link:https://www.youtube.com/watch?v=0d713-V4vrg[019^] +
-Demonstrates how Apache Isis' xref:guides/ugvw.adoc[Wicket viewer] remembers the state of rendered domain objects, and how the end-user of the
+Demonstrates how Apache Isis' xref:guides/ugvw.adoc#[Wicket viewer] remembers the state of rendered domain objects, and how the end-user of the
  application can clear these UI hints using the (framework-provided) xref:guides/rgcms.adoc#__rgcms_classes_mixins_Object_clearHints["clear hints"] action.
 |||x||||||||
 
 
 
 |link:https://www.youtube.com/watch?v=Kqch-XNlBMA[020^] +
-Demonstrates how the end-user can copy and share URLs for domain objects - including UI hints - using Apache Isis' xref:guides/ugvw.adoc[Wicket viewer].
+Demonstrates how the end-user can copy and share URLs for domain objects - including UI hints - using Apache Isis' xref:guides/ugvw.adoc#[Wicket viewer].
 |||x||||||||
 
 
 
 |link:https://www.youtube.com/watch?v=a0QQLT_16To[021^] +
-Demonstrates how the end-user can use bookmarks and breadcrumbs within Apache Isis' xref:guides/ugvw.adoc[Wicket viewer], and how the developer can ensure that xref:guides/rgant.adoc#_rgant-DomainObjectLayout_bookmarking[domain objects] and (xref:guides/rgant.adoc#_rgant-Action_semantics[query-only]) xref:guides/rgant.adoc#_rgant-ActionLayout_bookmarking[actions] can be bookmarked.
+Demonstrates how the end-user can use bookmarks and breadcrumbs within Apache Isis' xref:guides/ugvw.adoc#[Wicket viewer], and how the developer can ensure that xref:guides/rgant.adoc#_rgant-DomainObjectLayout_bookmarking[domain objects] and (xref:guides/rgant.adoc#_rgant-Action_semantics[query-only]) xref:guides/rgant.adoc#_rgant-ActionLayout_bookmarking[actions] can be bookmarked.
 |||x||||||||
 
 
@@ -426,7 +426,7 @@ include::_screencasts-playlists.adoc[]
 
 
 |link:https://www.youtube.com/watch?v=esujf_DFeWA[041^] +
-Using BigDecimal as a property within a domain object, also demonstrating the "summary" view within the xref:guides/ugvw.adoc[Wicket viewer].
+Using BigDecimal as a property within a domain object, also demonstrating the "summary" view within the xref:guides/ugvw.adoc#[Wicket viewer].
 |||||||x||x|x|
 
 
@@ -552,7 +552,7 @@ The (very simple) steps required to rename a domain entity class.
 
 
 |link:https://www.youtube.com/watch?v=J5xobU6X0ng[057^] +
-How to rename a menu (on the top-level menubar) as rendered in the xref:guides/ugvw.adoc[Wicket viewer].
+How to rename a menu (on the top-level menubar) as rendered in the  xref:guides/ugvw.adoc#[Wicket viewer].
 |x||||||||||
 
 

[51/58] [abbrv] isis git commit: wip - ugfun.adoc , crud

[da...@apache.org]

wip - ugfun.adoc , crud


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/842c5b43
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/842c5b43
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/842c5b43

Branch: refs/heads/wip
Commit: 842c5b43d700ef1fe9f0b55f8cab41fe25ca5c7a
Parents: 2693c5c
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Mon Apr 17 21:01:45 2017 +0200
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Thu Apr 20 09:09:31 2017 +0100

----------------------------------------------------------------------
 .../main/asciidoc/guides/ugfun/_ugfun_crud.adoc |  2 ++
 .../guides/ugfun/_ugfun_crud_deleting.adoc      | 18 ++++++++++++++
 .../guides/ugfun/_ugfun_crud_finding.adoc       |  6 +++++
 .../guides/ugfun/_ugfun_crud_instantiating.adoc |  2 +-
 .../guides/ugfun/_ugfun_crud_persisting.adoc    | 14 +++++++++++
 .../guides/ugfun/_ugfun_crud_updating.adoc      | 25 ++++++++++++++++++++
 6 files changed, 66 insertions(+), 1 deletion(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/842c5b43/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud.adoc
index add909f..a34e7d3 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud.adoc
@@ -22,6 +22,8 @@ include::_ugfun_crud_persisting.adoc[leveloffset=+1]
 
 include::_ugfun_crud_finding.adoc[leveloffset=+1]
 
+include::_ugfun_crud_updating.adoc[leveloffset=+1]
+
 include::_ugfun_crud_deleting.adoc[leveloffset=+1]
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/842c5b43/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_deleting.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_deleting.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_deleting.adoc
index edb0257..015edf4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_deleting.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_deleting.adoc
@@ -4,10 +4,28 @@
 :_basedir: ../../
 :_imagesdir: images/
 
+Domain entities can be deleted using xref:../rgsvc/rgsvc.adoc#_rgsvc_api_RepositoryService[`RepositoryService`].
+For example:
 
+[source,java]
+----
+Customer customer = ...
+repositoryService.remove(customer);
+----
 
+It's worth being aware that (as for persisting new entities) the framework does _not_ eagerly delete the object.
+Rather, it queues up an internal command structure representing the object deletion request.
+This is then executed either at the end of the transaction, or if a  xref:../ugfun/ugfun.adoc#_ugfun_crud_finding[query is run], or if the internal queue is manually flushed using xref:../rgsvc/rgsvc.adoc#_rgsvc_api_TransactionService[`TransactionService`]'s `flush()` method.
 
+Alternatively, you can use:
 
+[source,java]
+----
+repositoryService.removeAndFlush(customer);
+----
 
+to eagerly perform the object deletion from the database.
+
+When an object is deleted the framework will emit `ObjectRemovingEvent` xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_events_lifecycle-events[lifecycle event].
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/842c5b43/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_finding.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_finding.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_finding.adoc
index 9b542ae..971245b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_finding.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_finding.adoc
@@ -53,6 +53,12 @@ public class CustomerRepository {
 <3> Corresponds to the `@Query#name()` attribute
 <4> Corresponds to the `:name` parameter in the query JDOQL string
 
+Whenever a query is submitted, the framework will automatically "flush" any pending changes.
+This ensures that the database query runs against an up-to-date table so that all matching instances (with respect to the current transaction) are correctly retrieved.
+
+
+When an object is loaded from the database the framework will emit `ObjectLoadedEvent` xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_events_lifecycle-events[lifecycle event].
+
 
 == Using DataNucleus type-safe queries
 

http://git-wip-us.apache.org/repos/asf/isis/blob/842c5b43/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_instantiating.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_instantiating.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_instantiating.adoc
index 7eae5c8..1ed757d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_instantiating.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_instantiating.adoc
@@ -21,7 +21,7 @@ or
 Dashboard dashboardVM = factoryService.instantiate(Dashboard.class);
 ----
 
-When the framework instantiates the object, all services are injected into the framework, and an `ObjectCreated` xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_events_lifecycle-events[lifecycle event] will also be emitted.
+When the framework instantiates the object, all services are injected into the framework, and an `ObjectCreatedEvent` xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_events_lifecycle-events[lifecycle event] will also be emitted.
 
 
 For this to work the target class _must_ have a no-arg constructor.

http://git-wip-us.apache.org/repos/asf/isis/blob/842c5b43/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_persisting.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_persisting.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_persisting.adoc
index c169866..8b18b60 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_persisting.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_persisting.adoc
@@ -30,6 +30,20 @@ customer.setLastName(lastName);
 repositoryService.persist(customer);
 ----
 
+It's worth being aware that the framework does _not_ eagerly persist the object.
+Rather, it queues up an internal command structure representing the object persistence request.
+This is then executed either at the end of the transaction, or if a xref:../ugfun/ugfun.adoc#_ugfun_crud_finding[query is run], or if the internal queue is manually flushed using xref:../rgsvc/rgsvc.adoc#_rgsvc_api_TransactionService[`TransactionService`]'s `flush()` method.
+
+Alternatively, you can use:
+
+[source,java]
+----
+repositoryService.persistAndFlush(customer);
+----
+
+to eagerly perform the object insertion into the database.
+
+When an object is persisted the framework will emit `ObjectPersistingEvent` and `ObjectPersistedEvent` xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_events_lifecycle-events[lifecycle events].
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/842c5b43/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_updating.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_updating.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_updating.adoc
new file mode 100644
index 0000000..ee07bad
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_updating.adoc
@@ -0,0 +1,25 @@
+[[_ugfun_crud_updating]]
+= Updating Objects
+: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/
+
+
+
+There is no specific API to update a domain entity.
+Rather, the ORM (DataNucleus) automatically keeps track of the state of each object and will update the corresponding database rows when the transaction completes.
+
+That said, it is possible to "flush" pending changes:
+
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_TransactionService[`TransactionService`] acts at the Apache Isis layer, and flushes any pending object persistence or object deletions
+
+* using xref:../rgsvc/rgsvc.adoc#_rgsvc_api_IsisJdoSupport[`IsisJdoSupport`] it is possible to reach down to the underlying JDO API, and perform a flush of pending object updates also.
+
+
+When an object is updated the framework will emit `ObjectUpdatingEvent` and `ObjectUpdatedEvent` xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_events_lifecycle-events[lifecycle events].
+
+
+
+
+
+

[32/58] [abbrv] isis git commit: ISIS-1521: fixes further xref links between guides

[da...@apache.org]

ISIS-1521: fixes further xref links between guides


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/b2b87ca4
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/b2b87ca4
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/b2b87ca4

Branch: refs/heads/wip
Commit: b2b87ca4a0d8c5eb76347415bd26539ac8ccaaab
Parents: 252c2f8
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Fri Apr 14 15:30:05 2017 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Thu Apr 20 09:09:30 2017 +0100

----------------------------------------------------------------------
 .../guides/dg/_dg_asciidoc-templates.adoc       | 30 ++++++++++----------
 .../asciidoc/guides/dg/_dg_hints-and-tips.adoc  |  2 +-
 ...nd-tips_how-run-fixtures-on-app-startup.adoc |  2 +-
 ...ts-and-tips_i18n-label-in-wicket-viewer.adoc |  2 +-
 .../guides/dg/_dg_working-with-many-repos.adoc  |  2 +-
 .../asciidoc/guides/rgant/_rgant-Action.adoc    |  2 +-
 .../guides/rgant/_rgant-ActionLayout.adoc       |  4 +--
 .../rgant/_rgant-ActionLayout_bookmarking.adoc  |  8 +++---
 .../rgant/_rgant-ActionLayout_cssClass.adoc     |  2 +-
 .../rgant/_rgant-ActionLayout_cssClassFa.adoc   |  2 +-
 .../rgant/_rgant-ActionLayout_describedAs.adoc  |  4 +--
 .../rgant/_rgant-ActionLayout_hidden.adoc       |  2 +-
 .../guides/rgant/_rgant-ActionLayout_named.adoc |  4 +--
 .../rgant/_rgant-ActionLayout_position.adoc     |  4 +--
 .../guides/rgant/_rgant-Action_command.adoc     |  4 +--
 .../guides/rgant/_rgant-Action_semantics.adoc   |  2 +-
 .../guides/rgant/_rgant-CollectionLayout.adoc   |  2 +-
 .../rgant/_rgant-CollectionLayout_cssClass.adoc |  2 +-
 .../_rgant-CollectionLayout_defaultView.adoc    |  4 +--
 .../_rgant-CollectionLayout_describedAs.adoc    |  4 +--
 .../rgant/_rgant-CollectionLayout_hidden.adoc   |  2 +-
 .../rgant/_rgant-CollectionLayout_named.adoc    |  4 +--
 .../rgant/_rgant-CollectionLayout_paged.adoc    |  4 +--
 .../rgant/_rgant-CollectionLayout_render.adoc   |  2 +-
 .../rgant/_rgant-CollectionLayout_sortedBy.adoc |  4 +--
 .../rgant/_rgant-Collection_domainEvent.adoc    |  2 +-
 .../guides/rgant/_rgant-Collection_editing.adoc |  2 +-
 .../guides/rgant/_rgant-Collection_hidden.adoc  |  6 ++--
 .../guides/rgant/_rgant-Discriminator.adoc      |  6 ++--
 .../guides/rgant/_rgant-DomainObjectLayout.adoc |  2 +-
 .../_rgant-DomainObjectLayout_bookmarking.adoc  |  4 +--
 ...gant-DomainObjectLayout_cssClassUiEvent.adoc |  4 +--
 .../_rgant-DomainObjectLayout_describedAs.adoc  |  2 +-
 .../_rgant-DomainObjectLayout_iconUiEvent.adoc  |  4 +--
 .../rgant/_rgant-DomainObjectLayout_named.adoc  |  2 +-
 .../rgant/_rgant-DomainObjectLayout_paged.adoc  |  2 +-
 .../_rgant-DomainObjectLayout_titleUiEvent.adoc |  4 +--
 .../rgant/_rgant-DomainObject_bounded.adoc      |  2 +-
 .../rgant/_rgant-DomainObject_nature.adoc       |  2 +-
 .../rgant/_rgant-DomainObject_objectType.adoc   |  6 ++--
 .../guides/rgant/_rgant-DomainService.adoc      |  2 +-
 .../rgant/_rgant-DomainServiceLayout.adoc       |  4 +--
 .../_rgant-DomainServiceLayout_menuBar.adoc     |  4 +--
 .../_rgant-DomainServiceLayout_menuOrder.adoc   |  2 +-
 .../rgant/_rgant-DomainService_nature.adoc      |  2 +-
 .../rgant/_rgant-DomainService_objectType.adoc  |  6 ++--
 .../asciidoc/guides/rgant/_rgant-HomePage.adoc  |  2 +-
 .../asciidoc/guides/rgant/_rgant-Inject.adoc    |  2 +-
 .../guides/rgant/_rgant-MemberGroupLayout.adoc  |  2 +-
 .../guides/rgant/_rgant-MemberOrder.adoc        |  2 +-
 .../asciidoc/guides/rgant/_rgant-Mixin.adoc     |  2 +-
 .../guides/rgant/_rgant-ParameterLayout.adoc    |  2 +-
 .../_rgant-ParameterLayout_describedAs.adoc     |  2 +-
 .../_rgant-ParameterLayout_labelPosition.adoc   |  2 +-
 .../rgant/_rgant-ParameterLayout_named.adoc     |  2 +-
 .../_rgant-ParameterLayout_typicalLength.adoc   |  2 +-
 .../guides/rgant/_rgant-PersistenceCapable.adoc |  6 ++--
 .../guides/rgant/_rgant-PostConstruct.adoc      |  2 +-
 .../guides/rgant/_rgant-PropertyLayout.adoc     |  2 +-
 .../rgant/_rgant-PropertyLayout_cssClass.adoc   |  2 +-
 .../_rgant-PropertyLayout_describedAs.adoc      |  4 +--
 .../rgant/_rgant-PropertyLayout_hidden.adoc     |  6 ++--
 .../_rgant-PropertyLayout_labelPosition.adoc    |  4 +--
 .../rgant/_rgant-PropertyLayout_multiLine.adoc  |  2 +-
 .../rgant/_rgant-PropertyLayout_named.adoc      |  4 +--
 ...gant-PropertyLayout_renderedAsDayBefore.adoc |  2 +-
 .../_rgant-PropertyLayout_typicalLength.adoc    |  2 +-
 .../guides/rgant/_rgant-Property_hidden.adoc    |  2 +-
 .../guides/rgant/_rgant-ViewModelLayout.adoc    |  2 +-
 .../_rgant-ViewModelLayout_describedAs.adoc     |  2 +-
 .../rgant/_rgant-ViewModelLayout_named.adoc     |  2 +-
 .../rgant/_rgant-ViewModelLayout_paged.adoc     |  2 +-
 .../rgant/_rgant-ViewModel_objectType.adoc      |  6 ++--
 .../guides/rgant/_rgant-XmlJavaTypeAdapter.adoc |  2 +-
 .../guides/rgant/_rgant-XmlRootElement.adoc     |  8 +++---
 .../guides/rgant/_rgant_aaa_deprecated.adoc     | 10 +++----
 .../asciidoc/guides/rgant/_rgant_aaa_jdo.adoc   |  6 ++--
 .../asciidoc/guides/rgant/_rgant_aaa_jee.adoc   |  2 +-
 .../asciidoc/guides/rgant/_rgant_aaa_main.adoc  |  4 +--
 .../asciidoc/guides/rgant/_rgant_aaa_other.adoc |  2 +-
 .../rgcfg/_rgcfg_configuration-files.adoc       |  4 +--
 .../guides/rgcfg/_rgcfg_configuring-core.adoc   | 22 +++++++-------
 .../guides/rgcfg/_rgcfg_deployment-types.adoc   | 10 +++----
 .../rgcfg/_rgcfg_specifying-components.adoc     |  2 +-
 .../src/main/asciidoc/guides/rgcfg/rgcfg.adoc   |  6 ++--
 .../asciidoc/guides/rgcms/_rgcms_classes.adoc   |  2 +-
 ...rgcms_classes_AppManifest-bootstrapping.adoc |  8 +++---
 .../_rgcms_classes_i18n_TranslatableString.adoc |  2 +-
 .../guides/rgcms/_rgcms_classes_layout.adoc     |  4 +--
 .../guides/rgcms/_rgcms_classes_mixins_Dto.adoc |  2 +-
 .../rgcms/_rgcms_classes_mixins_Object.adoc     |  6 ++--
 .../_rgcms_classes_super_FixtureScript.adoc     |  2 +-
 .../_rgcms_classes_super_FixtureScripts.adoc    |  2 +-
 .../guides/rgcms/_rgcms_methods_prefixes.adoc   |  8 +++---
 .../rgcms/_rgcms_methods_prefixes_addTo.adoc    |  2 +-
 .../rgcms/_rgcms_methods_prefixes_disable.adoc  |  6 ++--
 .../rgcms/_rgcms_methods_prefixes_hide.adoc     |  2 +-
 .../_rgcms_methods_prefixes_removeFrom.adoc     |  2 +-
 .../rgcms/_rgcms_methods_prefixes_validate.adoc |  2 +-
 .../_rgcms_methods_prefixes_validateAddTo.adoc  |  4 +--
 ...cms_methods_prefixes_validateRemoveFrom.adoc |  4 +--
 .../rgcms/_rgcms_methods_reserved_cssClass.adoc |  2 +-
 .../rgcms/_rgcms_methods_reserved_disable.adoc  |  2 +-
 .../rgcms/_rgcms_methods_reserved_getId.adoc    |  6 ++--
 .../rgcms/_rgcms_methods_reserved_iconName.adoc |  2 +-
 .../rgcms/_rgcms_methods_reserved_title.adoc    |  2 +-
 .../rgcms/_rgcms_methods_reserved_validate.adoc |  2 +-
 .../_rgfis_spi_ContentNegotiationService.adoc   |  8 +++---
 .../rgfis/_rgfis_spi_RepresentationService.adoc |  2 +-
 .../asciidoc/guides/rgmvn/_rgmvn_intro.adoc     |  2 +-
 .../asciidoc/guides/rgmvn/_rgmvn_swagger.adoc   |  2 +-
 .../asciidoc/guides/rgmvn/_rgmvn_validate.adoc  |  2 +-
 .../main/asciidoc/guides/rgmvn/_rgmvn_xsd.adoc  |  2 +-
 .../rgsvc/_rgsvc_api_AcceptHeaderService.adoc   |  2 +-
 .../_rgsvc_api_ActionInvocationContext.adoc     |  2 +-
 .../guides/rgsvc/_rgsvc_api_CommandContext.adoc |  4 +--
 .../rgsvc/_rgsvc_api_DeepLinkService.adoc       |  6 ++--
 ..._api_DomainObjectContainer_messages-api.adoc |  8 +++---
 ..._api_DomainObjectContainer_security-api.adoc |  4 +--
 .../guides/rgsvc/_rgsvc_api_EmailService.adoc   |  4 +--
 .../rgsvc/_rgsvc_api_FixtureScriptsDefault.adoc |  2 +-
 .../rgsvc/_rgsvc_api_GuiceBeanProvider.adoc     |  8 +++---
 .../rgsvc/_rgsvc_api_InteractionContext.adoc    |  2 +-
 .../guides/rgsvc/_rgsvc_api_IsisJdoSupport.adoc |  2 +-
 .../guides/rgsvc/_rgsvc_api_JaxbService.adoc    |  2 +-
 .../guides/rgsvc/_rgsvc_api_MementoService.adoc |  4 +--
 .../guides/rgsvc/_rgsvc_api_MessageService.adoc |  8 +++---
 .../guides/rgsvc/_rgsvc_api_Scratchpad.adoc     |  4 +--
 .../guides/rgsvc/_rgsvc_api_SudoService.adoc    |  6 ++--
 .../guides/rgsvc/_rgsvc_api_SwaggerService.adoc |  6 ++--
 .../rgsvc/_rgsvc_api_SwitchUserService.adoc     |  2 +-
 .../rgsvc/_rgsvc_api_TransactionService.adoc    |  2 +-
 .../guides/rgsvc/_rgsvc_api_UserService.adoc    |  4 +--
 .../guides/rgsvc/_rgsvc_api_WrapperFactory.adoc |  4 +--
 .../rgsvc/_rgsvc_application-layer-api.adoc     |  2 +-
 .../asciidoc/guides/rgsvc/_rgsvc_intro.adoc     |  4 +--
 .../guides/rgsvc/_rgsvc_metadata-api.adoc       |  2 +-
 .../rgsvc/_rgsvc_presentation-layer-spi.adoc    |  2 +-
 .../guides/rgsvc/_rgsvc_spi_AuditerService.adoc |  2 +-
 .../rgsvc/_rgsvc_spi_AuditingService.adoc       |  2 +-
 .../_rgsvc_spi_BackgroundCommandService.adoc    |  4 +--
 .../guides/rgsvc/_rgsvc_spi_CommandService.adoc |  4 +--
 .../rgsvc/_rgsvc_spi_ContentMappingService.adoc |  4 +--
 .../_rgsvc_spi_EmailNotificationService.adoc    |  4 +--
 .../rgsvc/_rgsvc_spi_ExceptionRecognizer.adoc   |  2 +-
 .../rgsvc/_rgsvc_spi_GridSystemService.adoc     |  2 +-
 .../guides/rgsvc/_rgsvc_spi_HintStore.adoc      |  4 +--
 .../guides/rgsvc/_rgsvc_spi_LocaleProvider.adoc |  8 +++---
 .../rgsvc/_rgsvc_spi_PublisherService.adoc      |  2 +-
 .../rgsvc/_rgsvc_spi_PublishingService.adoc     |  2 +-
 .../guides/rgsvc/_rgsvc_spi_RoutingService.adoc |  2 +-
 .../rgsvc/_rgsvc_spi_TranslationService.adoc    |  6 ++--
 .../rgsvc/_rgsvc_spi_TranslationsResolver.adoc  |  8 +++---
 .../rgsvc/_rgsvc_spi_UrlEncodingService.adoc    |  2 +-
 .../rgsvc/_rgsvc_spi_UserProfileService.adoc    |  2 +-
 .../_rgsvc_spi_UserRegistrationService.adoc     |  4 +--
 .../ugbtb/_ugbtb_decoupling_contributions.adoc  |  2 +-
 .../ugbtb/_ugbtb_decoupling_db-schemas.adoc     |  2 +-
 .../guides/ugbtb/_ugbtb_decoupling_mixins.adoc  |  4 +--
 .../_ugbtb_decoupling_pushing-changes.adoc      |  2 +-
 ...b_deployment_externalized-configuration.adoc |  4 +--
 .../ugbtb/_ugbtb_deployment_jvm-flags.adoc      |  2 +-
 .../guides/ugbtb/_ugbtb_deployment_tomcat.adoc  |  4 +--
 .../guides/ugbtb/_ugbtb_headless-access.adoc    |  4 +--
 ...dless-access_BackgroundCommandExecution.adoc |  2 +-
 .../main/asciidoc/guides/ugbtb/_ugbtb_i18n.adoc | 12 ++++----
 ...ther-techniques_transactions-and-errors.adoc |  8 +++---
 .../_ugbtb_programming-model_finetuning.adoc    |  2 +-
 ...rogramming-model_layout-metadata-reader.adoc |  2 +-
 .../guides/ugbtb/_ugbtb_view-models_jaxb.adoc   | 20 ++++++-------
 .../ugbtb/_ugbtb_view-models_use-cases.adoc     | 12 ++++----
 .../asciidoc/guides/ugbtb/_ugbtb_web-xml.adoc   |  6 ++--
 .../src/main/asciidoc/guides/ugbtb/ugbtb.adoc   |  4 +--
 ...ugfun_core-concepts_apache-isis-vs_cqrs.adoc |  6 ++--
 ...core-concepts_apache-isis-vs_metawidget.adoc |  2 +-
 ...ache-isis-vs_mvc-server-side-frameworks.adoc |  4 +--
 .../_ugfun_core-concepts_building-blocks.adoc   | 18 ++++++------
 ..._core-concepts_other-deployment-options.adoc |  2 +-
 .../_ugfun_core-concepts_philosophy_aop.adoc    |  4 +--
 .../ugfun/_ugfun_core-concepts_principles.adoc  |  4 +--
 ...e-concepts_principles_for-the-long-term.adoc |  2 +-
 ...fun_getting-started_simpleapp-archetype.adoc | 12 ++++----
 .../ugfun/_ugfun_how-tos_class-structure.adoc   |  4 +--
 ...ow-tos_class-structure_class-definition.adoc |  6 ++--
 ...fun_how-tos_class-structure_collections.adoc |  4 +--
 ...gfun_how-tos_class-structure_properties.adoc |  4 +--
 .../ugfun/_ugfun_how-tos_domain-services.adoc   |  2 +-
 ...n_how-tos_ui-hints_action-icons-and-css.adoc |  2 +-
 .../ugfun/_ugfun_how-tos_ui-hints_layout.adoc   |  2 +-
 ...how-tos_ui-hints_names-and-descriptions.adoc |  2 +-
 ...ow-tos_ui-hints_object-titles-and-icons.adoc |  4 +--
 .../ugfun/_ugfun_how-tos_ui_are-you-sure.adoc   |  2 +-
 .../src/main/asciidoc/guides/ugfun/ugfun.adoc   |  2 +-
 .../guides/ugodn/_ugodn_configuring.adoc        |  2 +-
 ...onfiguring_eagerly-registering-entities.adoc |  2 +-
 .../ugodn/_ugodn_configuring_properties.adoc    |  4 +--
 .../_ugsec_configuring-isis-to-use-shiro.adoc   |  2 +-
 .../guides/ugsec/_ugsec_shiro-ini-realm.adoc    |  2 +-
 ...shiro-isis-enhanced-wildcard-permission.adoc |  2 +-
 .../ugsec/_ugsec_usage-by-isis-viewers.adoc     | 12 ++++----
 .../_ugtst_bdd-spec-support_key-classes.adoc    |  2 +-
 ...tst_bdd-spec-support_writing-a-bdd-spec.adoc |  2 +-
 .../_ugtst_fixture-scripts_api-and-usage.adoc   |  4 +--
 ..._ugtst_integ-test-support_bootstrapping.adoc |  6 ++--
 ...gtst_integ-test-support_wrapper-factory.adoc |  2 +-
 .../guides/ugvro/_ugvro_architecture.adoc       |  4 +--
 .../ugvro/_ugvro_configuration-properties.adoc  |  8 +++---
 .../asciidoc/guides/ugvro/_ugvro_ro-spec.adoc   |  6 ++--
 .../_ugvro_simplified-representations.adoc      |  6 ++--
 ...epresentations_configuration-properties.adoc |  2 +-
 .../ugvw/_ugvw_configuration-properties.adoc    | 16 +++++------
 ...guration-properties_abbreviating-titles.adoc |  2 +-
 ...ration-properties_showing-theme-chooser.adoc |  4 +--
 ...n-properties_suppressing-password-reset.adoc |  2 +-
 ...guration-properties_suppressing-sign-up.adoc |  2 +-
 .../ugvw/_ugvw_customisation_about-page.adoc    |  2 +-
 ...vw_customisation_cheap-n-cheerful-theme.adoc |  2 +-
 .../_ugvw_customisation_custom-javascript.adoc  |  2 +-
 .../ugvw/_ugvw_customisation_default-theme.adoc |  2 +-
 ...ugvw_customisation_tweaking-css-classes.adoc |  6 ++--
 .../asciidoc/guides/ugvw/_ugvw_extending.adoc   | 12 ++++----
 .../_ugvw_extending_custom-bootstrap-theme.adoc |  2 +-
 .../ugvw/_ugvw_extending_custom-pages.adoc      |  2 +-
 ..._ugvw_extending_replacing-page-elements.adoc |  2 +-
 .../ugvw/_ugvw_features_blob-attachments.adoc   |  2 +-
 .../ugvw/_ugvw_features_bookmarked-pages.adoc   |  4 +--
 .../ugvw/_ugvw_features_hints-and-copy-url.adoc |  2 +-
 .../ugvw/_ugvw_features_recent-pages.adoc       |  4 +--
 .../ugvw/_ugvw_features_titles-in-tables.adoc   |  2 +-
 .../ugvw/_ugvw_features_user-registration.adoc  |  2 +-
 .../asciidoc/guides/ugvw/_ugvw_isis-addons.adoc |  2 +-
 .../ugvw/_ugvw_layout_annotation-based.adoc     |  4 +--
 .../ugvw/_ugvw_layout_application-menu.adoc     |  2 +-
 .../guides/ugvw/_ugvw_layout_file-based.adoc    |  4 +--
 234 files changed, 455 insertions(+), 455 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc-templates.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc-templates.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc-templates.adoc
index 8c8fc58..8ccd418 100644
--- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc-templates.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc-templates.adoc
@@ -309,7 +309,7 @@ for example:
 
 
 |`adugvw`
-|`\xref:ugvw.adoc#xxx[ttt]`
+|`\xref:../ugvw/ugvw.adoc#xxx[ttt]`
 
 A hyperlink to a bookmark within the Wicket viewer guide, where:
 
@@ -318,13 +318,13 @@ A hyperlink to a bookmark within the Wicket viewer guide, where:
 
 for example:
 
-`\xref:ugvw.adoc#_ugvw_customisation[Customisation]`
+`\xref:../ugvw/ugvw.adoc#_ugvw_customisation[Customisation]`
 
-|xref:ugvw.adoc#_ugvw_customisation[Customisation]
+|xref:../ugvw/ugvw.adoc#_ugvw_customisation[Customisation]
 
 
 |`adugvro`
-|`\xref:ugvro.adoc#xxx[ttt]`
+|`\xref:../ugvro/ugvro.adoc#xxx[ttt]`
 
 A hyperlink to a bookmark within the Restful Objects viewer guide, where:
 
@@ -333,14 +333,14 @@ A hyperlink to a bookmark within the Restful Objects viewer guide, where:
 
 for example:
 
-`\xref:ugvro.adoc#_ugvro_ro-spec[RestfulObjects specification]`
+`\xref:../ugvro/ugvro.adoc#_ugvro_ro-spec[RestfulObjects specification]`
 
-|xref:ugvro.adoc#_ugvro_ro-spec[RestfulObjects specification]
+|xref:../ugvro/ugvro.adoc#_ugvro_ro-spec[RestfulObjects specification]
 
 
 
 |`adugsec`
-|`\xref:ugsec.adoc#xxx[ttt]`
+|`\xref:../ugsec/ugsec.adoc#xxx[ttt]`
 
 A hyperlink to a bookmark within the Secrurity guide, where:
 
@@ -349,13 +349,13 @@ A hyperlink to a bookmark within the Secrurity guide, where:
 
 for example:
 
-`\xref:ugsec.adoc#_ugsec_shiro-caching[Caching and other Shiro Features]`
+`\xref:../ugsec/ugsec.adoc#_ugsec_shiro-caching[Caching and other Shiro Features]`
 
-|xref:ugsec.adoc#_ugsec_shiro-caching[Caching and other Shiro Features]
+|xref:../ugsec/ugsec.adoc#_ugsec_shiro-caching[Caching and other Shiro Features]
 
 
 |`adugtst`
-|`\xref:ugtst.adoc#xxx[ttt]`
+|`\xref:../ugtst/ugtst.adoc#xxx[ttt]`
 
 A hyperlink to a bookmark within the Testing guide, where:
 
@@ -364,13 +364,13 @@ A hyperlink to a bookmark within the Testing guide, where:
 
 for example:
 
-`\xref:ugtst.adoc#_ugtst_bdd-spec-support[BDD Spec Support]`
+`\xref:../ugtst/ugtst.adoc#_ugtst_bdd-spec-support[BDD Spec Support]`
 
-|xref:ugtst.adoc#_ugtst_bdd-spec-support[BDD Spec Support]
+|xref:../ugtst/ugtst.adoc#_ugtst_bdd-spec-support[BDD Spec Support]
 
 
 |`adugbtb`
-|`\xref:ugbtb.adoc#xxx[ttt]`
+|`\xref:../ugbtb/ugbtb.adoc#xxx[ttt]`
 
 A hyperlink to a bookmark within the 'Beyond the Basics' user guide, where:
 
@@ -379,9 +379,9 @@ A hyperlink to a bookmark within the 'Beyond the Basics' user guide, where:
 
 for example:
 
-`\xref:ugbtb.adoc#_ugbtb_deployment_externalized-configuration[Externalized Configuration]`
+`\xref:../ugbtb/ugbtb.adoc#_ugbtb_deployment_externalized-configuration[Externalized Configuration]`
 
-|xref:ugbtb.adoc#_ugbtb_deployment_externalized-configuration[Externalized Configuration]
+|xref:../ugbtb/ugbtb.adoc#_ugbtb_deployment_externalized-configuration[Externalized Configuration]
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc
index 67d89bd..78cfee4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips.adoc
@@ -10,7 +10,7 @@
 This chapter has FAQs (with solutions) for problems we've encountered ourselves or have been raised on the
 Apache Isis mailing lists.
 
-See also xref:ugvro.adoc#_ugvro_hints-and-tips[Restful Objects hints-n-tips].
+See also xref:../ugvro/ugvro.adoc#_ugvro_hints-and-tips[Restful Objects hints-n-tips].
 
 include::_dg_hints-and-tips_enabling-logging.adoc[leveloffset=+1]
 include::_dg_hints-and-tips_subtype-entity-not-fully-populated.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-run-fixtures-on-app-startup.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-run-fixtures-on-app-startup.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-run-fixtures-on-app-startup.adoc
index 89a1547..cc930e4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-run-fixtures-on-app-startup.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_how-run-fixtures-on-app-startup.adoc
@@ -13,7 +13,7 @@ Hook up into the webapp start?
 Use events?_
 
 
-The standard approach is to use xref:ugtst.adoc#_ugtst_fixture-scripts[fixture scripts].
+The standard approach is to use xref:../ugtst/ugtst.adoc#_ugtst_fixture-scripts[fixture scripts].
 These can be run in on start-up typically by being specified in the xref:rgcsm.adoc#_rgcsm_classes_AppManifest-bootstrapping[`AppManifest`], see for
 example the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype].
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_i18n-label-in-wicket-viewer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_i18n-label-in-wicket-viewer.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_i18n-label-in-wicket-viewer.adoc
index 6a6b6ac..d4d16e0 100644
--- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_i18n-label-in-wicket-viewer.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_hints-and-tips_i18n-label-in-wicket-viewer.adoc
@@ -15,7 +15,7 @@ Can this be done?_
 
 The above FAQ was raised against `1.10.0`.  As of `1.11.0` (due to link:https://issues.apache.org/jira/browse/ISIS-1093[ISIS-1093]) it _is_ now possible to internationalize both the Wicket viewer's labels as well as the regular translations of the domain object metadata using the `.po` translation files as supported by the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_TranslationService[`TranslationService`].
 
-Full details of the ``msgId``s that must be added to the `translations.po` file can be found in xref:guides/ugbtb.adoc#__ugbtb_i18n_wicket-viewer[i18n] section of the xref:ugbtb.adoc#[beyond the basics] guide.
+Full details of the ``msgId``s that must be added to the `translations.po` file can be found in xref:guides/ugbtb.adoc#__ugbtb_i18n_wicket-viewer[i18n] section of the xref:../ugbtb/ugbtb.adoc#[beyond the basics] guide.
 
 In prior releases (`1.10.0` and earlier) it was necessary to use link:https://ci.apache.org/projects/wicket/guide/6.x/guide/i18n.html#i18n_3[Wicket's internationalization support], namely resource bundles.  This is still supported (as a fallback):
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/dg/_dg_working-with-many-repos.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_working-with-many-repos.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_working-with-many-repos.adoc
index 383341b..086f329 100644
--- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_working-with-many-repos.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_working-with-many-repos.adoc
@@ -8,7 +8,7 @@
 
 Applications built with Apache Isis often (should) consist of multiple modules, each in separate git repositories.  For example, there are the various (non-ASF) link:http://isisaddons.org[Isis Addons] that provide various cross-cutting concerns/technical services (security, mail-merge etc), as well the modules eg as provided by the (non-ASF) link:http://catalog.incode.org[Incode Catalog], which provides generic business subdomains (communication channels, documents etc).
 
-In addition, your own application may well be structured as a number of distinct modules (probably with the entities in each module being mapped to a different schema), and using such techniques as the xref:ugbtb.adoc#_ugbtb_decoupling_event-bus[event bus] and xref:ugbtb.adoc#_ugbtb_decoupling_mixins[mixins] so that these modules are decoupled from each other.
+In addition, your own application may well be structured as a number of distinct modules (probably with the entities in each module being mapped to a different schema), and using such techniques as the xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_event-bus[event bus] and xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_mixins[mixins] so that these modules are decoupled from each other.
 
 All of which is a preamble to say that you will likely have multiple directories on your local development computer, for each such git repository that you contribute to.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action.adoc
index 4ee7904..907d042 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action.adoc
@@ -81,7 +81,7 @@ Currently this is only supported for no-arg actions.
 (`NON_IDEMPOTENT`)
 |the action's semantics (ie whether objects are modified as the result of invoking this action, and if so whether reinvoking the action would result in no further change; if not whether the results can be cached for the remainder of the request).
 
-The `...ARE_YOU_SURE` variants cause a confirmation dialog to be displayed in the xref:ugvw.adoc#[Wicket viewer].
+The `...ARE_YOU_SURE` variants cause a confirmation dialog to be displayed in the xref:../ugvw/ugvw.adoc#[Wicket viewer].
 
 |xref:../rgant/rgant.adoc#_rgant-Action_typeOf[`typeOf()`]
 |(none)

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout.adoc
index ef22d3c..7dd4a26 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout.adoc
@@ -36,7 +36,7 @@ For a domain service action to be contributed, the domain services must have a x
 |Any string valid as a CSS class
 |an additional CSS class around the HTML that represents for the action, to allow targetted styling in xref:../rgcfg/rgcfg.adoc#_rgcfg_application-specific_application-css[`application.css`]. +
 
-Supported by the xref:ugvw.adoc#[Wicket viewer] but currently ignored by the xref:ugvro.adoc#[RestfulObjects viewer].
+Supported by the xref:../ugvw/ugvw.adoc#[Wicket viewer] but currently ignored by the xref:../ugvro/ugvro.adoc#[RestfulObjects viewer].
 
 
 |xref:../rgant/rgant.adoc#_rgant-ActionLayout_cssClassFa[`cssClassFa()`]
@@ -100,7 +100,7 @@ public class ToDoItems {
 
 [TIP]
 ====
-As an alternative to using the `@ActionLayout` annotation, a xref:ugvw.adoc#_ugvw_layout_file-based[file-based layout] can be used (and is generally to be preferred since it is more flexible/powerful).
+As an alternative to using the `@ActionLayout` annotation, a xref:../ugvw/ugvw.adoc#_ugvw_layout_file-based[file-based layout] can be used (and is generally to be preferred since it is more flexible/powerful).
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_bookmarking.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_bookmarking.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_bookmarking.adoc
index 643f24e..da095d4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_bookmarking.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_bookmarking.adoc
@@ -10,18 +10,18 @@ The `bookmarking()` attribute indicates if an action (with safe xref:../rgant/rg
 
 
 
-In the xref:ugvw.adoc#[Wicket viewer], a link to a bookmarked object is shown in the bookmarks panel:
+In the xref:../ugvw/ugvw.adoc#[Wicket viewer], a link to a bookmarked object is shown in the bookmarks panel:
 
 image::{_imagesdir}reference-annotations/ActionLayout/bookmarking.png[width="720px",link="{_imagesdir}reference-annotations/ActionLayout/bookmarking.png"]
 
 [NOTE]
 ====
-Note that this screenshot shows an earlier version of the xref:ugvw.adoc#[Wicket viewer] UI (specifically, pre 1.8.0).
+Note that this screenshot shows an earlier version of the xref:../ugvw/ugvw.adoc#[Wicket viewer] UI (specifically, pre 1.8.0).
 ====
 
 [TIP]
 ====
-The xref:ugvw.adoc#[Wicket viewer] supports `alt-[` as a shortcut for opening the bookmark panel.  `Esc` will close.
+The xref:../ugvw/ugvw.adoc#[Wicket viewer] supports `alt-[` as a shortcut for opening the bookmark panel.  `Esc` will close.
 ====
 
 
@@ -50,7 +50,7 @@ The enum value `AS_CHILD` has no meaning for actions; it relates only to bookmar
 
 
 
-As an alternative to using the annotation, the dynamic xref:ugvw.adoc#_ugvw_layout_file-based[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:../ugvw/ugvw.adoc#_ugvw_layout_file-based[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_cssClass.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_cssClass.adoc
index 56b6d84..d59294e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_cssClass.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_cssClass.adoc
@@ -30,7 +30,7 @@ to apply CSS, specifically to add http://fortawesome.github.io/Font-Awesome/icon
 
 
 
-As an alternative to using the annotation, the dynamic xref:ugvw.adoc#_ugvw_layout_file-based[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:../ugvw/ugvw.adoc#_ugvw_layout_file-based[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_cssClassFa.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_cssClassFa.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_cssClassFa.adoc
index 2b642cd..f072cf3 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_cssClassFa.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_cssClassFa.adoc
@@ -31,7 +31,7 @@ public class ToDoItem {
 There can be multiple "fa-" classes, eg to mirror or rotate the icon. There is no need to include the mandatory `fa` "marker" CSS class; it will be automatically added to the list.  The `fa-` prefix can also be omitted from the class names; it will be prepended to each if required.
 
 
-As an alternative to using the annotation, the dynamic xref:ugvw.adoc#_ugvw_layout_file-based[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:../ugvw/ugvw.adoc#_ugvw_layout_file-based[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_describedAs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_describedAs.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_describedAs.adoc
index 7818a0d..e9b5655 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_describedAs.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_describedAs.adoc
@@ -6,7 +6,7 @@
 
 
 
-The `describedAs()` attribute is used to provide a short description of the action to the user.  In the xref:ugvw.adoc#[Wicket viewer] it is displayed as a 'tool tip'.
+The `describedAs()` attribute is used to provide a short description of the action to the user.  In the xref:../ugvw/ugvw.adoc#[Wicket viewer] it is displayed as a 'tool tip'.
 
 This attribute can also be specified for xref:../rgant/rgant.adoc#_rgant-CollectionLayout_describedAs[collections],  xref:../rgant/rgant.adoc#_rgant-PropertyLayout_describedAs[properties], xref:../rgant/rgant.adoc#_rgant-ParameterLayout_describedAs[parameters], xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_describedAs[domain objects] and xref:../rgant/rgant.adoc#_rgant-ViewModelLayout_describedAs[view models].
 
@@ -24,7 +24,7 @@ public class Customer {
 
 
 
-As an alternative to using the annotation, the dynamic xref:ugvw.adoc#_ugvw_layout_file-based[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:../ugvw/ugvw.adoc#_ugvw_layout_file-based[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_hidden.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_hidden.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_hidden.adoc
index a1ad7d4..f5696ee 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_hidden.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_hidden.adoc
@@ -37,7 +37,7 @@ The action should not be hidden.
 The other values of the `Where` enum have no meaning for a collection.
 
 
-As an alternative to using the annotation, the dynamic xref:ugvw.adoc#_ugvw_layout_file-based[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:../ugvw/ugvw.adoc#_ugvw_layout_file-based[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_named.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_named.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_named.adoc
index d50b1f8..9ca98f9 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_named.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_named.adoc
@@ -25,7 +25,7 @@ public class Customer {
 ----
 
 
-As an alternative to using the annotation, the dynamic xref:ugvw.adoc#_ugvw_layout_file-based[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:../ugvw/ugvw.adoc#_ugvw_layout_file-based[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]
@@ -38,7 +38,7 @@ can be used instead, eg:
 
 [TIP]
 ====
-The framework also provides a separate, powerful mechanism for xref:ugbtb.adoc#_ugbtb_i18n[internationalization].
+The framework also provides a separate, powerful mechanism for xref:../ugbtb/ugbtb.adoc#_ugbtb_i18n[internationalization].
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_position.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_position.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_position.adoc
index 89cba44..1fe7e60 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_position.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ActionLayout_position.adoc
@@ -40,7 +40,7 @@ public class Customer {
 <3> give the action an abbreviated name, because the fact that the "status" property is to be updated is implied by its positioning
 
 
-The default is `BELOW`, which is rendered (by the xref:ugvw.adoc#[Wicket viewer]) as shown below:
+The default is `BELOW`, which is rendered (by the xref:../ugvw/ugvw.adoc#[Wicket viewer]) as shown below:
 
 image::{_imagesdir}reference-annotations/ActionLayout/position-BELOW.png[width="720px",link="{_imagesdir}reference-annotations/ActionLayout/position-BELOW.png"]
 
@@ -67,7 +67,7 @@ image::{_imagesdir}reference-annotations/ActionLayout/position-PANEL_DROPDOWN.pn
 If there are multiple actions associated with a single property then the positioning can be mix'ed-and-match'ed as required.  If the `PANEL` or `PANEL_DROPDOWN` are used, then (as the screenshots above show) the actions from potentially multiple properties grouped by that panel will be shown together.
 
 
-As an alternative to using the annotation, the dynamic xref:ugvw.adoc#_ugvw_layout_file-based[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:../ugvw/ugvw.adoc#_ugvw_layout_file-based[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_command.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_command.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_command.adoc
index 16ab6ce..70bcb77 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_command.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_command.adoc
@@ -23,7 +23,7 @@ By default, actions are invoked in directly in the thread of the invocation.   I
 
 [NOTE]
 ====
-If background ``Command``s are used, then an external scheduler, using xref:ugbtb.adoc#_ugbtb_headless-access_BackgroundCommandExecution[headless access], must also be configured.
+If background ``Command``s are used, then an external scheduler, using xref:../ugbtb/ugbtb.adoc#_ugbtb_headless-access_BackgroundCommandExecution[headless access], must also be configured.
 ====
 
 
@@ -112,7 +112,7 @@ will prevent the parent `Command` object from being persisted, _even if_ a child
 
 For persisted commands, the `commandExecuteIn()` attribute determines whether the `Command` should be executed in the foreground (the default) or executed in the background.
 
-Background execution means that the command is not executed immediately, but is available for a configured xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[`BackgroundCommandService`] to execute, eg by way of an in-memory scheduler such as Quartz.  See xref:ugbtb.adoc#_ugbtb_headless-access_BackgroundCommandExecution[here] for further information on this topic.
+Background execution means that the command is not executed immediately, but is available for a configured xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[`BackgroundCommandService`] to execute, eg by way of an in-memory scheduler such as Quartz.  See xref:../ugbtb/ugbtb.adoc#_ugbtb_headless-access_BackgroundCommandExecution[here] for further information on this topic.
 
 For example:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_semantics.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_semantics.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_semantics.adoc
index e3f3a13..9a10041 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_semantics.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_semantics.adoc
@@ -8,7 +8,7 @@
 
 The `semantics()` attribute describes whether the invocation modifies state of the system, and if so whether it does so idempotently.  If the action invocation does _not_ modify the state of the system, in other words is safe, then it also can beused to specify whether the results of the action can be cached automatically for the remainder of the request.
 
-The attribute was originally introduced for the xref:ugvro.adoc#[RestfulObjects viewer] in order that action invocations could be using the appropriate `HTTP` verb (`GET`, `PUT` and `POST`).
+The attribute was originally introduced for the xref:../ugvro/ugvro.adoc#[RestfulObjects viewer] in order that action invocations could be using the appropriate `HTTP` verb (`GET`, `PUT` and `POST`).
 
 The table below summarizes the semantics:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout.adoc
index 88a0f52..f9891c3 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout.adoc
@@ -96,7 +96,7 @@ public class ToDoItem {
 
 [TIP]
 ====
-As an alternative to using the `@CollectionLayout` annotation, a xref:ugvw.adoc#_ugvw_layout_file-based[file-based layout] can be used (and is generally to be preferred since it is more flexible/powerful).
+As an alternative to using the `@CollectionLayout` annotation, a xref:../ugvw/ugvw.adoc#_ugvw_layout_file-based[file-based layout] can be used (and is generally to be preferred since it is more flexible/powerful).
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_cssClass.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_cssClass.adoc
index d5834c4..f9664f7 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_cssClass.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_cssClass.adoc
@@ -24,7 +24,7 @@ public class ToDoItem {
 ----
 
 
-As an alternative to using the annotation, the dynamic xref:ugvw.adoc#_ugvw_layout_file-based[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:../ugvw/ugvw.adoc#_ugvw_layout_file-based[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_defaultView.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_defaultView.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_defaultView.adoc
index 9955a3b..a3f71d2 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_defaultView.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_defaultView.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-The xref:ugvw.adoc#[Wicket viewer] allows additional views to be configured to render collections of objects; at the time of writing thesee include the (non-ASF) (non-ASF) link:http://isisaddons.org[Isis Addons]' (non-ASF) http://github.com/isisaddons/isis-wicket-excel[excel] view, the http://github.com/isisaddons/isis-wicket-fullcalendar2[fullcalendar2] view, and the http://github.com/isisaddons/isis-wicket-gmap3[gmap3] view.  If the objects to be rendered have the correct "shape", then the appropriate view will be made available.  For example, objects with a date can be rendered using `calendar`; objects with locations can be rendered using `map`.
+The xref:../ugvw/ugvw.adoc#[Wicket viewer] allows additional views to be configured to render collections of objects; at the time of writing thesee include the (non-ASF) (non-ASF) link:http://isisaddons.org[Isis Addons]' (non-ASF) http://github.com/isisaddons/isis-wicket-excel[excel] view, the http://github.com/isisaddons/isis-wicket-fullcalendar2[fullcalendar2] view, and the http://github.com/isisaddons/isis-wicket-gmap3[gmap3] view.  If the objects to be rendered have the correct "shape", then the appropriate view will be made available.  For example, objects with a date can be rendered using `calendar`; objects with locations can be rendered using `map`.
 
 The `defaultView()` attribute is used to select which of these views should be used by default for a given collection.
 
@@ -24,7 +24,7 @@ public class BusRoute {
 ----
 
 
-As an alternative to using the annotation, the dynamic xref:ugvw.adoc#_ugvw_layout_file-based[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:../ugvw/ugvw.adoc#_ugvw_layout_file-based[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_describedAs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_describedAs.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_describedAs.adoc
index 7695b9b..56037be 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_describedAs.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_describedAs.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-The `describedAs()` attribute is used to provide a short description of the collection to the user.  In the xref:ugvw.adoc#[Wicket viewer] it is displayed as a 'tool tip'.
+The `describedAs()` attribute is used to provide a short description of the collection to the user.  In the xref:../ugvw/ugvw.adoc#[Wicket viewer] it is displayed as a 'tool tip'.
 
 The `describedAs()` attribute can also be specified for xref:../rgant/rgant.adoc#_rgant-PropertyLayout_describedAs[properties], xref:../rgant/rgant.adoc#_rgant-ActionLayout_describedAs[actions], xref:../rgant/rgant.adoc#_rgant-ParameterLayout_describedAs[parameters], xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_describedAs[domain objects] and xref:../rgant/rgant.adoc#_rgant-ViewModelLayout_describedAs[view models].
 
@@ -24,7 +24,7 @@ public class ToDoItem {
 ----
 
 
-As an alternative to using the annotation, the dynamic xref:ugvw.adoc#_ugvw_layout_file-based[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:../ugvw/ugvw.adoc#_ugvw_layout_file-based[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_hidden.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_hidden.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_hidden.adoc
index 5156638..88b6c5a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_hidden.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_hidden.adoc
@@ -47,7 +47,7 @@ The collection should not be hidden.
 The other values of the `Where` enum have no meaning for a collection.
 
 
-As an alternative to using the annotation, the dynamic xref:ugvw.adoc#_ugvw_layout_file-based[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:../ugvw/ugvw.adoc#_ugvw_layout_file-based[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_named.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_named.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_named.adoc
index d58a60c..8c12d3c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_named.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_named.adoc
@@ -33,7 +33,7 @@ public class ToDoItem {
 
 
 
-As an alternative to using the annotation, the dynamic xref:ugvw.adoc#_ugvw_layout_file-based[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:../ugvw/ugvw.adoc#_ugvw_layout_file-based[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]
@@ -49,5 +49,5 @@ can be used instead, eg:
 
 [TIP]
 ====
-The framework also provides a separate, powerful mechanism for xref:ugbtb.adoc#_ugbtb_i18n[internationalization].
+The framework also provides a separate, powerful mechanism for xref:../ugbtb/ugbtb.adoc#_ugbtb_i18n[internationalization].
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_paged.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_paged.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_paged.adoc
index f3d7569..e578a16 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_paged.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_paged.adoc
@@ -10,7 +10,7 @@ The `paged()` attribute specifies the number of rows to display in a (parented)
 
 [WARNING]
 ====
-The xref:ugvro.adoc#[RestfulObjects viewer] currently does not support paging.   The xref:ugvw.adoc#[Wicket viewer] _does_ support paging, but note that the paging is performed client-side rather than server-side.
+The xref:../ugvro/ugvro.adoc#[RestfulObjects viewer] currently does not support paging.   The xref:../ugvw/ugvw.adoc#[Wicket viewer] _does_ support paging, but note that the paging is performed client-side rather than server-side.
 
 We therefore recommend that large collections should instead be modelled as actions (to allow filtering to be applied to limit the number of rows).
 ====
@@ -31,7 +31,7 @@ It is also possible to specify a global default for the page size of standalone
 
 
 
-As an alternative to using the annotation, the dynamic xref:ugvw.adoc#_ugvw_layout_file-based[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:../ugvw/ugvw.adoc#_ugvw_layout_file-based[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_render.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_render.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_render.adoc
index eaeeda2..9a1b0d4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_render.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_render.adoc
@@ -20,7 +20,7 @@ public class Order {
 ----
 
 
-As an alternative to using the annotation, the dynamic xref:ugvw.adoc#_ugvw_layout_file-based[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:../ugvw/ugvw.adoc#_ugvw_layout_file-based[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_sortedBy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_sortedBy.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_sortedBy.adoc
index bc01ff1..0b4e4c2 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_sortedBy.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-CollectionLayout_sortedBy.adoc
@@ -37,7 +37,7 @@ image::{_imagesdir}reference-annotations/CollectionLayout/sortedby-dependencies.
 
 [NOTE]
 ====
-Note that this screenshot shows an earlier version of the xref:ugvw.adoc#[Wicket viewer] UI (specifically, pre 1.8.0).
+Note that this screenshot shows an earlier version of the xref:../ugvw/ugvw.adoc#[Wicket viewer] UI (specifically, pre 1.8.0).
 ====
 
 
@@ -46,7 +46,7 @@ Without this annotation, the order would have been inverted (because the natural
 
 
 
-As an alternative to using the annotation, the dynamic xref:ugvw.adoc#_ugvw_layout_file-based[`.layout.json`]
+As an alternative to using the annotation, the dynamic xref:../ugvw/ugvw.adoc#_ugvw_layout_file-based[`.layout.json`]
 can be used instead, eg:
 
 [source,javascript]

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection_domainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection_domainEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection_domainEvent.adoc
index 254fa62..801a584 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection_domainEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection_domainEvent.adoc
@@ -18,7 +18,7 @@ Subscribers subscribe through the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusSe
 
 [WARNING]
 ====
-The xref:ugvw.adoc#[Wicket viewer] does _not_ currently support the modification of collections; they are rendered read-only.  However, domain events are still relevant to determine if such collections should be hidden.
+The xref:../ugvw/ugvw.adoc#[Wicket viewer] does _not_ currently support the modification of collections; they are rendered read-only.  However, domain events are still relevant to determine if such collections should be hidden.
 
 The workaround is to create add/remove actions and use xref:../rgant/rgant.adoc#_rgant-MemberOrder[UI hints] to render them close to the collection.
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection_editing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection_editing.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection_editing.adoc
index 3310952..c578545 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection_editing.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection_editing.adoc
@@ -12,7 +12,7 @@ The related `editingDisabledReason()` attribute specifies the a hard-coded reaso
 
 [WARNING]
 ====
-The xref:ugvw.adoc#[Wicket viewer] does *not* currently support the modification of collections; they are rendered read-only.
+The xref:../ugvw/ugvw.adoc#[Wicket viewer] does *not* currently support the modification of collections; they are rendered read-only.
 
 The workaround is to create add/remove actions and use xref:../rgant/rgant.adoc#_rgant-MemberOrder[UI hints] to render them close to the collection.
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection_hidden.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection_hidden.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection_hidden.adoc
index 63da074..e252f41 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection_hidden.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection_hidden.adoc
@@ -9,7 +9,7 @@ Collections can be hidden at the domain-level, indicating that they are not visi
 
 [TIP]
 ====
-It is also possible to use xref:../rgant/rgant.adoc#_rgant-CollectionLayout_hidden[`@CollectionLayout#hidden()`] or using xref:ugvw.adoc#_ugvw_layout_file-based[file-based layout] such that the collection can be hidden at the view layer.
+It is also possible to use xref:../rgant/rgant.adoc#_rgant-CollectionLayout_hidden[`@CollectionLayout#hidden()`] or using xref:../ugvw/ugvw.adoc#_ugvw_layout_file-based[file-based layout] such that the collection can be hidden at the view layer.
 Both options are provided with a view that in the future the view-layer semantics may be under the control of (expert) users, whereas domain-layer semantics should never be overridden or modified by the user.
 ====
 
@@ -49,7 +49,7 @@ The other values of the `Where` enum have no meaning for a collection.
 
 [NOTE]
 ====
-The xref:ugvw.adoc#[Wicket viewer] suppresses collections when displaying lists of objects.
+The xref:../ugvw/ugvw.adoc#[Wicket viewer] suppresses collections when displaying lists of objects.
 
-The xref:ugvro.adoc#[RestfulObjects viewer] by default suppress collections when rendering a domain object.
+The xref:../ugvro/ugvro.adoc#[RestfulObjects viewer] by default suppress collections when rendering a domain object.
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Discriminator.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Discriminator.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Discriminator.adoc
index 6f7716d..450534c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Discriminator.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Discriminator.adoc
@@ -24,8 +24,8 @@ This can appear in several contexts, including:
  (see xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`])
  ** and thus in the "table-of-two-halves" pattern, as per (non-ASF) http://github.com/isisaddons/isis-module-poly[Isis addons' poly] module
 * in the serialization of `OidDto` in the xref:../rgcms/rgcms.adoc#_rgcms_schema-cmd[command] and xref:../rgcms/rgcms.adoc#_rgcms_schema-ixn[interaction] schemas
-* in the URLs of the xref:ugvro.adoc#[RestfulObjects viewer]
-* in the URLs of the xref:ugvw.adoc#[Wicket viewer] (in general and in particular if xref:ugvw.adoc#_ugvw_features_hints-and-copy-url[copying URLs])
+* in the URLs of the xref:../ugvro/ugvro.adoc#[RestfulObjects viewer]
+* in the URLs of the xref:../ugvw/ugvw.adoc#[Wicket viewer] (in general and in particular if xref:../ugvw/ugvw.adoc#_ugvw_features_hints-and-copy-url[copying URLs])
 * in XML snapshots generated by the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_XmlSnapshotService[`XmlSnapshotService`]
 
 
@@ -64,7 +64,7 @@ If only `schema` is defined, then the value is "`schema.className`".
 This might be obvious, but to make explicit: we recommend that you always specify an object type for your domain objects.
 
 Otherwise, if you refactor your code (change class name or move package), then any externally held references to the OID of the object will break.
-At best this will require a data migration in the database; at worst it could cause external clients accessing data through the xref:ugvro.adoc#[Restful Objects] viewer to break.
+At best this will require a data migration in the database; at worst it could cause external clients accessing data through the xref:../ugvro/ugvro.adoc#[Restful Objects] viewer to break.
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout.adoc
index df4b445..7bef931 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout.adoc
@@ -109,7 +109,7 @@ public class ToDoItem {
 
 [NOTE]
 ====
-Note that there is (currently) no support for specifying UI hints for domain objects through the dynamic xref:ugvw.adoc#_ugvw_layout_file-based[`.layout.json`] file (only for properties, collections and actions are supported).
+Note that there is (currently) no support for specifying UI hints for domain objects through the dynamic xref:../ugvw/ugvw.adoc#_ugvw_layout_file-based[`.layout.json`] file (only for properties, collections and actions are supported).
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_bookmarking.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_bookmarking.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_bookmarking.adoc
index 5829ea1..98cb467 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_bookmarking.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_bookmarking.adoc
@@ -14,7 +14,7 @@ image::{_imagesdir}reference-annotations/DomainObjectLayout/bookmarking.png[widt
 
 [NOTE]
 ====
-Note that this screenshot shows an earlier version of the xref:ugvw.adoc#[Wicket viewer] UI (specifically, pre 1.8.0).
+Note that this screenshot shows an earlier version of the xref:../ugvw/ugvw.adoc#[Wicket viewer] UI (specifically, pre 1.8.0).
 ====
 
 For example:
@@ -37,7 +37,7 @@ image::{_imagesdir}reference-annotations/DomainObjectLayout/bookmarking-nested.p
 
 [NOTE]
 ====
-Note that this screenshot shows an earlier version of the xref:ugvw.adoc#[Wicket viewer] UI (specifically, pre 1.8.0).
+Note that this screenshot shows an earlier version of the xref:../ugvw/ugvw.adoc#[Wicket viewer] UI (specifically, pre 1.8.0).
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_cssClassUiEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_cssClassUiEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_cssClassUiEvent.adoc
index 0b1f983..8b948aa 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_cssClassUiEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_cssClassUiEvent.adoc
@@ -17,8 +17,8 @@ the domain object using the event's API.
 [NOTE]
 ====
 The feature was originally introduced so that xref:../rgant/rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`]-annotated
-xref:ugbtb.adoc#_ugbtb_view-models[view model]s could be kept as minimal as possible, just defining the data.
-UI events allow subscribers to provide UI hints, while xref:ugbtb.adoc#_ugbtb_decoupling_mixins[mixin]s can be used to provide the behaviour.
+xref:../ugbtb/ugbtb.adoc#_ugbtb_view-models[view model]s could be kept as minimal as possible, just defining the data.
+UI events allow subscribers to provide UI hints, while xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_mixins[mixin]s can be used to provide the behaviour.
 ====
 
 By default the event raised is `CssClassUiEvent.Default`. For example:

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_describedAs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_describedAs.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_describedAs.adoc
index 0c026da..23c1650 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_describedAs.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_describedAs.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-The `describedAs()` attribute is used to provide a short description of the domain object to the user.  In the xref:ugvw.adoc#[Wicket viewer] it is displayed as a 'tool tip'.  The attribute can also be specified for xref:../rgant/rgant.adoc#_rgant-CollectionLayout_describedAs[collections],  xref:../rgant/rgant.adoc#_rgant-PropertyLayout_describedAs[properties], xref:../rgant/rgant.adoc#_rgant-ActionLayout_describedAs[actions], xref:../rgant/rgant.adoc#_rgant-ParameterLayout_describedAs[parameters] and xref:../rgant/rgant.adoc#_rgant-ViewModelLayout_describedAs[view models].
+The `describedAs()` attribute is used to provide a short description of the domain object to the user.  In the xref:../ugvw/ugvw.adoc#[Wicket viewer] it is displayed as a 'tool tip'.  The attribute can also be specified for xref:../rgant/rgant.adoc#_rgant-CollectionLayout_describedAs[collections],  xref:../rgant/rgant.adoc#_rgant-PropertyLayout_describedAs[properties], xref:../rgant/rgant.adoc#_rgant-ActionLayout_describedAs[actions], xref:../rgant/rgant.adoc#_rgant-ParameterLayout_describedAs[parameters] and xref:../rgant/rgant.adoc#_rgant-ViewModelLayout_describedAs[view models].
 
 For example:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_iconUiEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_iconUiEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_iconUiEvent.adoc
index 2a48a2e..21d5f81 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_iconUiEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_iconUiEvent.adoc
@@ -18,8 +18,8 @@ the domain object using the event's API.
 [NOTE]
 ====
 The feature was originally introduced so that xref:../rgant/rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`]-annotated
-xref:ugbtb.adoc#_ugbtb_view-models[view model]s could be kept as minimal as possible, just defining the data.
-UI events allow subscribers to provide UI hints, while xref:ugbtb.adoc#_ugbtb_decoupling_mixins[mixin]s can be used to provide the behaviour.
+xref:../ugbtb/ugbtb.adoc#_ugbtb_view-models[view model]s could be kept as minimal as possible, just defining the data.
+UI events allow subscribers to provide UI hints, while xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_mixins[mixin]s can be used to provide the behaviour.
 ====
 
 By default the event raised is `IconUiEvent.Default`. For example:

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_named.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_named.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_named.adoc
index 4302409..c5e702e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_named.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_named.adoc
@@ -31,7 +31,7 @@ It's also possible to specify a xref:../rgant/rgant.adoc#_rgant-DomainObjectLayo
 
 [TIP]
 ====
-The framework also provides a separate, powerful mechanism for xref:ugbtb.adoc#_ugbtb_i18n[internationalization].
+The framework also provides a separate, powerful mechanism for xref:../ugbtb/ugbtb.adoc#_ugbtb_i18n[internationalization].
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_paged.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_paged.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_paged.adoc
index 8380c1b..fb206ee 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_paged.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_paged.adoc
@@ -11,7 +11,7 @@ The `paged()` attribute specifies the number of rows to display in a standalone
 
 [WARNING]
 ====
-The xref:ugvro.adoc#[RestfulObjects viewer] currently does not support paging.   The xref:ugvw.adoc#[Wicket viewer] _does_ support paging, but note that the paging is performed client-side rather than server-side.
+The xref:../ugvro/ugvro.adoc#[RestfulObjects viewer] currently does not support paging.   The xref:../ugvw/ugvw.adoc#[Wicket viewer] _does_ support paging, but note that the paging is performed client-side rather than server-side.
 
 We therefore recommend that large collections should instead be modelled as actions (to allow filtering to be applied to limit the number of rows).
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_titleUiEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_titleUiEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_titleUiEvent.adoc
index a36a421..aa1fb75 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_titleUiEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_titleUiEvent.adoc
@@ -17,8 +17,8 @@ the domain object using the event's API.
 [NOTE]
 ====
 The feature was originally introduced so that xref:../rgant/rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`]-annotated
-xref:ugbtb.adoc#_ugbtb_view-models[view model]s could be kept as minimal as possible, just defining the data.
-UI events allow subscribers to provide UI hints, while xref:ugbtb.adoc#_ugbtb_decoupling_mixins[mixin]s can be used to provide the behaviour.
+xref:../ugbtb/ugbtb.adoc#_ugbtb_view-models[view model]s could be kept as minimal as possible, just defining the data.
+UI events allow subscribers to provide UI hints, while xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_mixins[mixin]s can be used to provide the behaviour.
 ====
 
 By default the event raised is `TitleUiEvent.Default`. For example:

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_bounded.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_bounded.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_bounded.adoc
index 40a2c64..e81d72e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_bounded.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_bounded.adoc
@@ -8,7 +8,7 @@
 
 Some domain classes are immutable to the user, and moreover have only a fixed number of instances.  Often these are "reference" ("standing") data, or lookup data/pick lists.  Typical examples could include categories, countries, states, and tax or interest rate tables.
 
-Where the number of instances is relatively small, ie bounded, then the `bounded()` attribute can be used as a hint.  For such domain objects the framework will automatically allow instances to be selected; xref:ugvw.adoc#[Wicket viewer] displays these as a drop-down list.
+Where the number of instances is relatively small, ie bounded, then the `bounded()` attribute can be used as a hint.  For such domain objects the framework will automatically allow instances to be selected; xref:../ugvw/ugvw.adoc#[Wicket viewer] displays these as a drop-down list.
 
 
 For example:

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_nature.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_nature.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_nature.adoc
index a0e64c9..097e71b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_nature.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_nature.adoc
@@ -44,7 +44,7 @@ The identity of an inmemory entity is determined solely by the state of entity's
 +
 indicates that the domain object is part of the domain layer, and is contributing behaviour to objects of some other type as a mixin (also known as a trait).
 
-Equivalent to annotating with xref:../rgant/rgant.adoc#_rgant-Mixin[`@Mixin`].  For further discussion on using mixins, see xref:ugbtb.adoc#_ugbtb_decoupling_mixins[mixins] in the user guide.
+Equivalent to annotating with xref:../rgant/rgant.adoc#_rgant-Mixin[`@Mixin`].  For further discussion on using mixins, see xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_mixins[mixins] in the user guide.
 
 
 * `VIEW_MODEL` +

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_objectType.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_objectType.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_objectType.adoc
index adf3c50..78804b1 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_objectType.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_objectType.adoc
@@ -14,8 +14,8 @@ This can appear in several contexts, including:
  (see xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`])
  ** and thus in the "table-of-two-halves" pattern, as per (non-ASF) http://github.com/isisaddons/isis-module-poly[Isis addons' poly] module
 * in the serialization of `OidDto` in the xref:../rgcms/rgcms.adoc#_rgcms_schema-cmd[command] and xref:../rgcms/rgcms.adoc#_rgcms_schema-ixn[interaction] schemas
-* in the URLs of the xref:ugvro.adoc#[RestfulObjects viewer]
-* in the URLs of the xref:ugvw.adoc#[Wicket viewer] (in general and in particular if xref:ugvw.adoc#_ugvw_features_hints-and-copy-url[copying URLs])
+* in the URLs of the xref:../ugvro/ugvro.adoc#[RestfulObjects viewer]
+* in the URLs of the xref:../ugvw/ugvw.adoc#[Wicket viewer] (in general and in particular if xref:../ugvw/ugvw.adoc#_ugvw_features_hints-and-copy-url[copying URLs])
 * in XML snapshots generated by the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_XmlSnapshotService[`XmlSnapshotService`]
 
 
@@ -54,7 +54,7 @@ If only `schema` is defined, then the value is "`schema.className`".
 This might be obvious, but to make explicit: we recommend that you always specify an object type for your domain objects.
 
 Otherwise, if you refactor your code (change class name or move package), then any externally held references to the OID of the object will break.
-At best this will require a data migration in the database; at worst it could cause external clients accessing data through the xref:ugvro.adoc#[Restful Objects] viewer to break.
+At best this will require a data migration in the database; at worst it could cause external clients accessing data through the xref:../ugvro/ugvro.adoc#[Restful Objects] viewer to break.
 ====
 
 [NOTE]

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainService.adoc
index a1e1d18..77db9f0 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainService.adoc
@@ -24,7 +24,7 @@ The table below summarizes the annotation's attributes.
 
 |xref:../rgant/rgant.adoc#_rgant-DomainService_nature[`nature()`]
 |`VIEW`, `VIEW_MENU_ONLY`, `VIEW_CONTRIBUTIONS_ONLY`, `VIEW_REST_ONLY`, `DOMAIN` (`VIEW`)
-|the nature of this service: providing actions for menus, or as contributed actions, or for the xref:ugvro.adoc#[RestfulObjects REST API], or neither
+|the nature of this service: providing actions for menus, or as contributed actions, or for the xref:../ugvro/ugvro.adoc#[RestfulObjects REST API], or neither
 
 
 |xref:../rgant/rgant.adoc#_rgant-DomainService_objectType[`objectType()`]

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainServiceLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainServiceLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainServiceLayout.adoc
index 10674c7..817b8b6 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainServiceLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainServiceLayout.adoc
@@ -10,7 +10,7 @@ The `@DomainServiceLayout` annotation applies to domain services, collecting tog
 
 [TIP]
 ====
-You will also find some additional material in the xref:ugvw.adoc#_ugvw_layout_application-menu[object layout] chapter.
+You will also find some additional material in the xref:../ugvw/ugvw.adoc#_ugvw_layout_application-menu[object layout] chapter.
 ====
 
 
@@ -64,7 +64,7 @@ public class ToDoItems {
 
 [NOTE]
 ====
-Note that there is (currently) no support for specifying UI hints for domain services through the dynamic xref:ugvw.adoc#_ugvw_layout_file-based[`.layout.json`] file (only for properties, collections and actions are supported).
+Note that there is (currently) no support for specifying UI hints for domain services through the dynamic xref:../ugvw/ugvw.adoc#_ugvw_layout_file-based[`.layout.json`] file (only for properties, collections and actions are supported).
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainServiceLayout_menuBar.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainServiceLayout_menuBar.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainServiceLayout_menuBar.adoc
index f300e81..77fafe8 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainServiceLayout_menuBar.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainServiceLayout_menuBar.adoc
@@ -19,7 +19,7 @@ public class ToDoItems {
 }
 ----
 
-In the xref:ugvw.adoc#[Wicket viewer], domain services placed on the `PRIMARY` menu bar appears to the left:
+In the xref:../ugvw/ugvw.adoc#[Wicket viewer], domain services placed on the `PRIMARY` menu bar appears to the left:
 
 image::{_imagesdir}reference-annotations/DomainServiceLayout/menuBar-primary.png[width="720px",link="{_imagesdir}reference-annotations/DomainServiceLayout/menuBar-primary.png"]
 
@@ -38,6 +38,6 @@ The grouping of multiple domain services actions within a single drop-down is ma
 
 [NOTE]
 ====
-The xref:ugvro.adoc#[RestfulObjects viewer] does not support this attribute.
+The xref:../ugvro/ugvro.adoc#[RestfulObjects viewer] does not support this attribute.
 ====
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainServiceLayout_menuOrder.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainServiceLayout_menuOrder.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainServiceLayout_menuOrder.adoc
index 95fc52b..60e5c2f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainServiceLayout_menuOrder.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainServiceLayout_menuOrder.adoc
@@ -20,7 +20,7 @@ For example, the screenshot below shows the "prototyping" menu from the (non-ASF
 image::{_imagesdir}reference-annotations/DomainServiceLayout/menuOrder.png[width="500px",link="{_imagesdir}reference-annotations/DomainServiceLayout/menuOrder.png"]
 
 
-The xref:ugvw.adoc#[Wicket viewer] automatically places separators between actions from different domain services.  From this we can infer that there are actually five different domain services that are all rendered on the "prototyping" top-level menu.
+The xref:../ugvw/ugvw.adoc#[Wicket viewer] automatically places separators between actions from different domain services.  From this we can infer that there are actually five different domain services that are all rendered on the "prototyping" top-level menu.
 
 One of these is the todoapp's `DemoDomainEventSubscriptions` service:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainService_nature.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainService_nature.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainService_nature.adoc
index d53ca76..fa84ef3 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainService_nature.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainService_nature.adoc
@@ -25,7 +25,7 @@ The related xref:../rgant/rgant.adoc#_rgant-ActionLayout_contributedAs[`@ActionL
 
 * `VIEW_REST_ONLY` +
 +
-The service's actions are intended only to be listed in the REST API exposed by the xref:ugvro.adoc#[RestfulObjects viewer].
+The service's actions are intended only to be listed in the REST API exposed by the xref:../ugvro/ugvro.adoc#[RestfulObjects viewer].
 
 * `DOMAIN` +
 +

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainService_objectType.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainService_objectType.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainService_objectType.adoc
index 7ceca4d..0509a99 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainService_objectType.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainService_objectType.adoc
@@ -13,8 +13,8 @@ This can appear in several contexts, including:
 * as the value of `Bookmark#getObjectType()` and in the `toString()` value of `Bookmark`
  (see xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`])
 * in the serialization of `OidDto` in the xref:../rgcms/rgcms.adoc#_rgcms_schema-cmd[command] and xref:../rgcms/rgcms.adoc#_rgcms_schema-ixn[interaction] schemas
-* in the URLs of the xref:ugvro.adoc#[RestfulObjects viewer]
-* in the URLs of the xref:ugvw.adoc#[Wicket viewer] (specifically, for bookmarked actions)
+* in the URLs of the xref:../ugvro/ugvro.adoc#[RestfulObjects viewer]
+* in the URLs of the xref:../ugvw/ugvw.adoc#[Wicket viewer] (specifically, for bookmarked actions)
 
 
 
@@ -48,7 +48,7 @@ The rules of precedence are:
 This might be obvious, but to make explicit: we recommend that you always specify an object type for your domain services.
 
 Otherwise, if you refactor your code (change class name or move package), then any externally held references to the OID of the service will break.
-At best this will require a data migration in the database; at worst it could cause external clients accessing data through the xref:ugvro.adoc#[Restful Objects] viewer to break.
+At best this will require a data migration in the database; at worst it could cause external clients accessing data through the xref:../ugvro/ugvro.adoc#[Restful Objects] viewer to break.
 ====
 
 [NOTE]

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-HomePage.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-HomePage.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-HomePage.adoc
index 8875441..aa08e8a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-HomePage.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-HomePage.adoc
@@ -45,7 +45,7 @@ public class ToDoAppDashboard {
     public Blob exportToWordDoc() { ... }  // <1>
 }
 ----
-<1> associated using xref:ugvw.adoc#_ugvw_layout_file-based[file-based layout] with the `notYetComplete` collection.
+<1> associated using xref:../ugvw/ugvw.adoc#_ugvw_layout_file-based[file-based layout] with the `notYetComplete` collection.
 
 The other two actions shown in the above screenshot -- `exportAsXml` and `downloadLayout` -- are actually contributed to the `ToDoAppDashboard` through various domain services, as is the `downloadLayout` action.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Inject.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Inject.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Inject.adoc
index 6ba109e..faebc82 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Inject.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Inject.adoc
@@ -6,7 +6,7 @@
 
 
 
-Apache Isis automatically injects domain services into other domain services and also into domain objects and view models.  In fact, it also injects domain services into xref:ugtst.adoc#_ugtst_integ-test-support[integration tests] and xref:ugtst.adoc#_ugtst_fixture-scripts[fixture scripts].
+Apache Isis automatically injects domain services into other domain services and also into domain objects and view models.  In fact, it also injects domain services into xref:../ugtst/ugtst.adoc#_ugtst_integ-test-support[integration tests] and xref:../ugtst/ugtst.adoc#_ugtst_fixture-scripts[fixture scripts].
 
 [NOTE]
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-MemberGroupLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-MemberGroupLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-MemberGroupLayout.adoc
index f9400a5..22d14cd 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-MemberGroupLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-MemberGroupLayout.adoc
@@ -16,5 +16,5 @@ The annotation defines two attributes, `name()` and `sequence()`.  Broadly speak
 
 [IMPORTANT]
 ====
-As this is an important topic, there is a xref:ugvw.adoc#_ugvw_layout[separate chapter] that discussed object layout in full.
+As this is an important topic, there is a xref:../ugvw/ugvw.adoc#_ugvw_layout[separate chapter] that discussed object layout in full.
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/b2b87ca4/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-MemberOrder.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-MemberOrder.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-MemberOrder.adoc
index c813ea4..05d3d45 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-MemberOrder.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-MemberOrder.adoc
@@ -21,7 +21,7 @@ Collections are always rendered in the "last" column.  This can appear either be
 
 [IMPORTANT]
 ====
-As this is an important topic, there is a xref:ugvw.adoc#_ugvw_layout[separate chapter] that discussed object layout in full.
+As this is an important topic, there is a xref:../ugvw/ugvw.adoc#_ugvw_layout[separate chapter] that discussed object layout in full.
 ====