You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2019/09/24 07:10:51 UTC
[isis] 05/07: ISIS-2062: converts ug btb into single doc using
includes.
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch v2
in repository https://gitbox.apache.org/repos/asf/isis.git
commit efaaaf8730ceb92dc6b4dd4d4e9fa8d2ebf6565b
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Tue Sep 24 05:53:54 2019 +0100
ISIS-2062: converts ug btb into single doc using includes.
fixes references, hopefully.
---
.../toc/modules/devguide/pages/hints-and-tips.adoc | 14 ------------
.../_adoc-rg/modules/ant/pages/Action/command.adoc | 4 ++--
.../modules/ant/pages/Property/command.adoc | 4 ++--
core/_adoc-rg/modules/ant/pages/ViewModel.adoc | 2 +-
.../_adoc-rg/modules/ant/pages/XmlRootElement.adoc | 2 +-
core/_adoc-rg/modules/ant/pages/aaa/jdo.adoc | 2 +-
.../modules/cfg/pages/configuring-core.adoc | 10 ++++-----
.../modules/cfg/pages/deployment-types.adoc | 2 +-
.../pages/classes/AppManifest-bootstrapping.adoc | 2 +-
.../application-layer-api/CommandContext.adoc | 2 +-
.../application-layer-api/InteractionContext.adoc | 2 +-
.../BackgroundCommandService.adoc | 4 ++--
.../application-layer-spi/CommandService.adoc | 4 ++--
.../svc/pages/integration-api/EmailService.adoc | 2 +-
.../persistence-layer-spi/AuditerService.adoc | 2 +-
.../persistence-layer-spi/PublisherService.adoc | 2 +-
.../presentation-layer-spi/TranslationService.adoc | 4 ++--
core/_adoc-ug/modules/btb/nav.adoc | 12 ----------
core/_adoc-ug/modules/btb/pages/about.adoc | 1 +
core/_adoc-ug/modules/btb/pages/deployment.adoc | 2 ++
.../modules/btb/pages/deployment/cmd-line.adoc | 8 ++++++-
.../modules/btb/pages/deployment/docker.adoc | 2 ++
.../deployment/externalized-configuration.adoc | 8 ++++---
.../_adoc-ug/modules/btb/pages/deployment/gae.adoc | 2 ++
.../modules/btb/pages/deployment/jvm-flags.adoc | 2 ++
.../modules/btb/pages/deployment/neo4j.adoc | 2 ++
.../modules/btb/pages/deployment/tomcat.adoc | 4 +++-
.../modules/btb/pages/headless-access.adoc | 2 ++
.../AbstractIsisSessionTemplate.adoc | 2 ++
.../BackgroundCommandExecution.adoc | 4 +++-
.../_adoc-ug/modules/btb/pages/hints-and-tips.adoc | 26 +++++++++++-----------
.../btb/pages/hints-and-tips/are-you-sure.adoc | 4 +++-
.../how-to-handle-void-and-null-results.adoc | 4 +++-
.../how-to-implement-a-spellchecker.adoc | 4 +++-
.../btb/pages/hints-and-tips/multi-tenancy.adoc | 4 +++-
.../btb/pages/hints-and-tips/persisted-title.adoc | 4 +++-
.../btb/pages/hints-and-tips/pushing-changes.adoc | 4 +++-
.../replacing-default-service-implementations.adoc | 4 +++-
.../simulating-collections-of-values.adoc | 4 +++-
.../subclass-properties-in-tables.adoc | 4 +++-
.../hints-and-tips/transactions-and-errors.adoc | 4 +++-
.../pages/hints-and-tips/vetoing-visibility.adoc | 4 +++-
.../hints-and-tips/view-model-instantiation.adoc | 4 +++-
core/_adoc-ug/modules/btb/pages/i18n.adoc | 4 +++-
.../modules/btb/pages/other-techniques.adoc | 2 ++
.../modules/btb/pages/programming-model.adoc | 2 ++
.../pages/programming-model/custom-validator.adoc | 2 ++
.../btb/pages/programming-model/finetuning.adoc | 4 +++-
core/_adoc-ug/modules/btb/pages/web-xml.adoc | 2 ++
core/_adoc-ug/modules/fun/.asciidoctorconfig | 5 +++++
core/_adoc-ug/modules/fun/pages/core-concepts.adoc | 16 -------------
.../fun/pages/core-concepts/apache-isis-vs.adoc | 3 +++
.../pages/core-concepts/deployment-options.adoc | 6 ++---
.../fun/pages/core-concepts/philosophy.adoc | 6 +++++
.../philosophy/hexagonal-architecture.adoc | 2 +-
.../fun/pages/core-concepts/principles.adoc | 5 +++++
.../core-concepts/principles/isis-itself.adoc | 2 ++
.../fun/pages/programming-model/collections.adoc | 2 +-
.../jdo/_adoc/modules/ROOT/pages/configuring.adoc | 2 +-
.../_adoc/modules/ROOT/pages/hints-and-tips.adoc | 13 -----------
.../_adoc/modules/ROOT/pages/hints-and-tips.adoc | 13 -----------
.../_adoc/modules/mvn/pages/validate.adoc | 2 +-
.../_adoc/modules/ROOT/pages/hints-and-tips.adoc | 13 -----------
.../_adoc/modules/ROOT/pages/hints-and-tips.adoc | 13 -----------
64 files changed, 149 insertions(+), 159 deletions(-)
diff --git a/antora/components/toc/modules/devguide/pages/hints-and-tips.adoc b/antora/components/toc/modules/devguide/pages/hints-and-tips.adoc
index 899fb26..bd778c9 100644
--- a/antora/components/toc/modules/devguide/pages/hints-and-tips.adoc
+++ b/antora/components/toc/modules/devguide/pages/hints-and-tips.adoc
@@ -8,18 +8,4 @@ include::_attributes.adoc[]
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:toc:devguide:hints-and-tips.adoc[Developers'] guide (this chapter)
-
-* the xref:vw:ROOT:hints-and-tips.adoc[Wicket viewer] guide
-
-* the xref:vro:ROOT:hints-and-tips.adoc[Restful Objects viewer] guide
-
-* the xref:odn:ROOT:hints-and-tips.adoc[Datanucleus ObjectStore] guide
-
-* the xref:security:ROOT:hints-and-tips.adoc[Security] guide
-
-* the xref:ug:btb:hints-and-tips.adoc[Beyond the Basics] guide.
-
diff --git a/core/_adoc-rg/modules/ant/pages/Action/command.adoc b/core/_adoc-rg/modules/ant/pages/Action/command.adoc
index 308dca0..d5024b0 100644
--- a/core/_adoc-rg/modules/ant/pages/Action/command.adoc
+++ b/core/_adoc-rg/modules/ant/pages/Action/command.adoc
@@ -31,7 +31,7 @@ If there is an implementation of `BackgroundCommandService` (as the (non-ASF) li
[NOTE]
====
-If background ``Command``s are used, then an external scheduler, using xref:ug:btb:headless-access/BackgroundCommandExecution.adoc[headless access], must also be configured.
+If background ``Command``s are used, then an external scheduler, using xref:ug:btb:about.adoc#BackgroundCommandExecution[headless access], must also be configured.
====
@@ -278,7 +278,7 @@ If `command` is `DISABLED` or does not otherwise apply due to the action's decla
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:rg:svc:application-layer-spi/BackgroundCommandService.adoc[`BackgroundCommandService`] to execute, eg by way of an in-memory scheduler such as Quartz.
-See xref:ug:btb:headless-access/BackgroundCommandExecution.adoc[here] for further information on this topic.
+See xref:ug:btb:about.adoc#BackgroundCommandExecution[here] for further information on this topic.
For example:
diff --git a/core/_adoc-rg/modules/ant/pages/Property/command.adoc b/core/_adoc-rg/modules/ant/pages/Property/command.adoc
index ca6ff87..fafe56d 100644
--- a/core/_adoc-rg/modules/ant/pages/Property/command.adoc
+++ b/core/_adoc-rg/modules/ant/pages/Property/command.adoc
@@ -27,7 +27,7 @@ If there is an implementation of `BackgroundCommandService` (as the (non-ASF) li
[NOTE]
====
-If background ``Command``s are used, then an external scheduler, using xref:ug:btb:headless-access/BackgroundCommandExecution.adoc[headless access], must also be configured.
+If background ``Command``s are used, then an external scheduler, using xref:ug:btb:about.adoc#BackgroundCommandExecution[headless access], must also be configured.
====
== `command()` and `commandPersistence()`
@@ -192,7 +192,7 @@ If `command` is `DISABLED` or does not otherwise apply due to the action's decla
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:rg:svc:application-layer-spi/BackgroundCommandService.adoc[`BackgroundCommandService`] to execute, eg by way of an in-memory scheduler such as Quartz. See xref:ug:btb:headless-access/BackgroundCommandExecution.adoc[here] for further information on this topic.
+Background execution means that the command is not executed immediately, but is available for a configured xref:rg:svc:application-layer-spi/BackgroundCommandService.adoc[`BackgroundCommandService`] to execute, eg by way of an in-memory scheduler such as Quartz. See xref:ug:btb:about.adoc#BackgroundCommandExecution[here] for further information on this topic.
For example:
diff --git a/core/_adoc-rg/modules/ant/pages/ViewModel.adoc b/core/_adoc-rg/modules/ant/pages/ViewModel.adoc
index aba0d11..9cfbbb1 100644
--- a/core/_adoc-rg/modules/ant/pages/ViewModel.adoc
+++ b/core/_adoc-rg/modules/ant/pages/ViewModel.adoc
@@ -37,7 +37,7 @@ serviceRegistry.injectServicesInto(vm);
[TIP]
====
-See this xref:ug:btb:hints-and-tips/view-model-instantiation.adoc[tip] for further discussion about instantiating view models.
+See this xref:ug:btb:about.adoc#view-model-instantiation[tip] for further discussion about instantiating view models.
====
View models must have a no-arg constructor; this is used internally by the framework for subsequent "recreation".
diff --git a/core/_adoc-rg/modules/ant/pages/XmlRootElement.adoc b/core/_adoc-rg/modules/ant/pages/XmlRootElement.adoc
index c0745b0..45f5d53 100644
--- a/core/_adoc-rg/modules/ant/pages/XmlRootElement.adoc
+++ b/core/_adoc-rg/modules/ant/pages/XmlRootElement.adoc
@@ -29,7 +29,7 @@ This adapter converts any references to such domain entities using the `oidDto`
====
The memento string for view models is converted into a form compatible with use within a URL.
This is performed by the xref:rg:svc:presentation-layer-spi/UrlEncodingService.adoc[`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:ug:btb:hints-and-tips/replacing-default-service-implementations.adoc[here] in the user guide.
+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:ug:btb:about.adoc#replacing-default-service-implementations[here] in the user guide.
====
diff --git a/core/_adoc-rg/modules/ant/pages/aaa/jdo.adoc b/core/_adoc-rg/modules/ant/pages/aaa/jdo.adoc
index a9c2e12..1bdd7b6 100644
--- a/core/_adoc-rg/modules/ant/pages/aaa/jdo.adoc
+++ b/core/_adoc-rg/modules/ant/pages/aaa/jdo.adoc
@@ -43,7 +43,7 @@ Note that the discriminator overrides the object type that may otherwise be infe
|xref:rg:ant:NotPersistent.adoc[`@javax.jdo.annotations.` +
`NotPersistent`]
-|Used to determine whether to enforce or skip some xref:ug:btb:programming-model/custom-validator.adoc[metamodel validation] for `@Column` versus equivalent Isis annotations.
+|Used to determine whether to enforce or skip some xref:ug:btb:about.adoc#custom-validator[metamodel validation] for `@Column` versus equivalent Isis annotations.
|Domain / persistence
|Property
diff --git a/core/_adoc-rg/modules/cfg/pages/configuring-core.adoc b/core/_adoc-rg/modules/cfg/pages/configuring-core.adoc
index 5ba53fe..7cb8fc1 100644
--- a/core/_adoc-rg/modules/cfg/pages/configuring-core.adoc
+++ b/core/_adoc-rg/modules/cfg/pages/configuring-core.adoc
@@ -396,7 +396,7 @@ Metamodel validation is only done if full introspection is configured, see the `
|`FQCN`
|Custom implementation of `MetaModelValidator` (in the `org.apache.isis.core.metamodel.specloader.validator` package) +
-See xref:ug:btb:programming-model/custom-validator.adoc[Custom Validator] to learn more.
+See xref:ug:btb:about.adoc#custom-validator[Custom Validator] to learn more.
|`isis.reflector.validator.` +
`actionCollection` +
@@ -598,27 +598,27 @@ See xref:ug:fun:ui-hints/action-icons-and-css.adoc[UI hints] for more details.
|This property is now IGNORED.
It was previously used to customize the programming model, this should now be done using `facets.exclude` and `facets.include`.
-See xref:ug:btb:programming-model/finetuning.adoc[finetuning the programming model] for more details.
+See xref:ug:btb:about.adoc#finetuning[finetuning the programming model] for more details.
|`isis.reflector.facets.` +
`exclude`
|`FQCN`,`FQCN2`,...
|Fully qualified class names of (existing, built-in) facet factory classes to be included to the programming model. +
-See xref:ug:btb:programming-model/finetuning.adoc[finetuning the programming model] for more details.
+See xref:ug:btb:about.adoc#finetuning[finetuning the programming model] for more details.
|`isis.reflector.facets.` +
`include`
|`FQCN`,`FQCN2`,...
|Fully qualified class names of (new, custom) facet factory classes to be included to the programming model. +
-See xref:ug:btb:programming-model/finetuning.adoc[finetuning the programming model] for more details.
+See xref:ug:btb:about.adoc#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:vw:ROOT:layout/file-based.adoc[file-based layout]s. +
-See xref:ug:btb:programming-model/layout-metadata-reader.adoc[Layout Metadata Reader] for more information.
+See xref:ug:btb:about.adoc#layout-metadata-reader[Layout Metadata Reader] for more information.
diff --git a/core/_adoc-rg/modules/cfg/pages/deployment-types.adoc b/core/_adoc-rg/modules/cfg/pages/deployment-types.adoc
index e2bfca8..dd9fc1b 100644
--- a/core/_adoc-rg/modules/cfg/pages/deployment-types.adoc
+++ b/core/_adoc-rg/modules/cfg/pages/deployment-types.adoc
@@ -66,7 +66,7 @@ Wicket's mechanism for specifying the "configuration" is to use a context parame
Most Apache Isis applications will consist of at least the xref:vw:ROOT:about.adoc[Wicket viewer] and optionally the xref:vro:ROOT:about.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:ug:btb:web-xml/servlet-context-listeners.adoc[ `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:ug:btb:about.adoc#servlet-context-listeners[ `IsisWebAppBootstrapper`].
In this case the deployment type is specified through an Apache Isis-specific context parameter, called `isis.deploymentType`:
diff --git a/core/_adoc-rg/modules/cms/pages/classes/AppManifest-bootstrapping.adoc b/core/_adoc-rg/modules/cms/pages/classes/AppManifest-bootstrapping.adoc
index 1e8d35c..d6abb81 100644
--- a/core/_adoc-rg/modules/cms/pages/classes/AppManifest-bootstrapping.adoc
+++ b/core/_adoc-rg/modules/cms/pages/classes/AppManifest-bootstrapping.adoc
@@ -211,7 +211,7 @@ isis.appManifest=domainapp.app.MyAppAppManifest
* the second is also as a webapp, but from within the context of the IDE. +
+
-Here, it's common to use the `org.apache.isis.WebServer` class to launch your application from the xref:ug:btb:deployment/cmd-line.adoc[command line].
+Here, it's common to use the `org.apache.isis.WebServer` class to launch your application from the xref:ug:btb:about.adoc#cmd-line[command line].
This allows the `AppManifest` to be specified using the `-m` (or `--manifest`) flag: +
+
[source,ini]
diff --git a/core/_adoc-rg/modules/svc/pages/application-layer-api/CommandContext.adoc b/core/_adoc-rg/modules/svc/pages/application-layer-api/CommandContext.adoc
index 95c51c2..f3e4351 100644
--- a/core/_adoc-rg/modules/svc/pages/application-layer-api/CommandContext.adoc
+++ b/core/_adoc-rg/modules/svc/pages/application-layer-api/CommandContext.adoc
@@ -213,7 +213,7 @@ The xref:rg:svc:application-layer-api/CommandContext.adoc[`CommandContext`] serv
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:rg:ant:Action/command.adoc[`@Action#commandExecuteIn()`], or is explicitly created through the xref:rg:svc:application-layer-api/BackgroundService.adoc[`BackgroundService`], then the actual interaction/execution is deferred until some other mechanism invokes the command (eg as described xref:ug:btb:headless-access/BackgroundCommandExecution.adoc[here]).
+However, if the `Command` is annotated to run in the background (using xref:rg:ant:Action/command.adoc[`@Action#commandExecuteIn()`], or is explicitly created through the xref:rg:svc:application-layer-api/BackgroundService.adoc[`BackgroundService`], then the actual interaction/execution is deferred until some other mechanism invokes the command (eg as described xref:ug:btb:about.adoc#BackgroundCommandExecution[here]).
The persistence of background commands requires a configured xref:rg:svc:application-layer-spi/BackgroundCommandService.adoc[`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:rg:svc:application-layer-spi/CommandService.adoc[`CommandService`].
diff --git a/core/_adoc-rg/modules/svc/pages/application-layer-api/InteractionContext.adoc b/core/_adoc-rg/modules/svc/pages/application-layer-api/InteractionContext.adoc
index 388be58..c5c8080 100644
--- a/core/_adoc-rg/modules/svc/pages/application-layer-api/InteractionContext.adoc
+++ b/core/_adoc-rg/modules/svc/pages/application-layer-api/InteractionContext.adoc
@@ -195,6 +195,6 @@ Most of the time a `Command` will be followed directly by its corresponding `Int
is annotated to run in the background (using xref:rg:ant:Action/command.adoc[`@Action#commandExecuteIn()`], or
is explicitly created through the xref:rg:svc:application-layer-api/BackgroundService.adoc[`BackgroundService`], then the actual
interaction/execution is deferred until some other mechanism invokes the command (eg as described
-xref:ug:btb:headless-access/BackgroundCommandExecution.adoc[here]).
+xref:ug:btb:about.adoc#BackgroundCommandExecution[here]).
diff --git a/core/_adoc-rg/modules/svc/pages/application-layer-spi/BackgroundCommandService.adoc b/core/_adoc-rg/modules/svc/pages/application-layer-spi/BackgroundCommandService.adoc
index be82dbe..81311e6 100644
--- a/core/_adoc-rg/modules/svc/pages/application-layer-spi/BackgroundCommandService.adoc
+++ b/core/_adoc-rg/modules/svc/pages/application-layer-spi/BackgroundCommandService.adoc
@@ -36,7 +36,7 @@ public interface BackgroundCommandService2 {
== "Internal" SPI
-The `BackgroundCommandExecution` (in isis-core) is an abstract template class for xref:ug:btb:headless-access/AbstractIsisSessionTemplate.adoc[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:ug:btb:about.adoc#AbstractIsisSessionTemplate[headless access], that defines an abstract hook method to obtain background `Command`s to be executed:
[source,java]
----
@@ -88,7 +88,7 @@ The imperative approach involves explicitly calling the xref:rg:svc:application-
The (non-ASF) link:https://platform.incode.org[Incode Platform^]'s command module provides an implementation 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:rg:svc:application-layer-spi/CommandService.adoc[`CommandService`].
-If contributions are not required in the UI, these can be suppressed either using security or by implementing a xref:ug:btb:hints-and-tips/vetoing-visibility.adoc[vetoing subscriber].
+If contributions are not required in the UI, these can be suppressed either using security or by implementing a xref:ug:btb:about.adoc#vetoing-visibility[vetoing subscriber].
diff --git a/core/_adoc-rg/modules/svc/pages/application-layer-spi/CommandService.adoc b/core/_adoc-rg/modules/svc/pages/application-layer-spi/CommandService.adoc
index 0f4bc08..fe67e48 100644
--- a/core/_adoc-rg/modules/svc/pages/application-layer-spi/CommandService.adoc
+++ b/core/_adoc-rg/modules/svc/pages/application-layer-spi/CommandService.adoc
@@ -76,7 +76,7 @@ xref:rg:svc:application-layer-spi/CommandService.adoc[`BackgroundCommandService`
All of these 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:ug:btb:hints-and-tips/vetoing-visibility.adoc[vetoing subscriber].
+If contributions are not required in the UI, these can be suppressed either using security or by implementing a xref:ug:btb:about.adoc#vetoing-visibility[vetoing subscriber].
@@ -85,7 +85,7 @@ If contributions are not required in the UI, these can be suppressed either usin
The (non-ASF) link:https://platform.incode.org[Incode Platform^]'s command module provides an implementation 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:rg:svc:application-layer-spi/CommandService.adoc[`BackgroundCommandService`].
-If contributions are not required in the UI, these can be suppressed either using security or by implementing a xref:ug:btb:hints-and-tips/vetoing-visibility.adoc[vetoing subscriber].
+If contributions are not required in the UI, these can be suppressed either using security or by implementing a xref:ug:btb:about.adoc#vetoing-visibility[vetoing subscriber].
diff --git a/core/_adoc-rg/modules/svc/pages/integration-api/EmailService.adoc b/core/_adoc-rg/modules/svc/pages/integration-api/EmailService.adoc
index 563b3aa..3f5a7ff 100644
--- a/core/_adoc-rg/modules/svc/pages/integration-api/EmailService.adoc
+++ b/core/_adoc-rg/modules/svc/pages/integration-api/EmailService.adoc
@@ -175,7 +175,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:ug:btb:deployment/externalized-configuration.adoc[external configuration file], or programmatically using the xref:rg:cms:classes/AppManifest-bootstrapping.adoc[`AppManifest`].
+These configuration properties can be specified either in `isis.properties` or in an xref:ug:btb:about.adoc#AppManifest-bootstrapping[`AppManifest`].
// TODO: v2: confirm this is the case.
diff --git a/core/_adoc-rg/modules/svc/pages/persistence-layer-spi/AuditerService.adoc b/core/_adoc-rg/modules/svc/pages/persistence-layer-spi/AuditerService.adoc
index 7b593a0..6be1e5a 100644
--- a/core/_adoc-rg/modules/svc/pages/persistence-layer-spi/AuditerService.adoc
+++ b/core/_adoc-rg/modules/svc/pages/persistence-layer-spi/AuditerService.adoc
@@ -93,7 +93,7 @@ This will therefore display all audit entries that occurred in a given request/t
These services 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:ug:btb:hints-and-tips/vetoing-visibility.adoc[vetoing subscriber].
+If menu items or contributions are not required in the UI, these can be suppressed either using security or by implementing a xref:ug:btb:about.adoc#vetoing-visibility[vetoing subscriber].
diff --git a/core/_adoc-rg/modules/svc/pages/persistence-layer-spi/PublisherService.adoc b/core/_adoc-rg/modules/svc/pages/persistence-layer-spi/PublisherService.adoc
index 460070b..fd9993f 100644
--- a/core/_adoc-rg/modules/svc/pages/persistence-layer-spi/PublisherService.adoc
+++ b/core/_adoc-rg/modules/svc/pages/persistence-layer-spi/PublisherService.adoc
@@ -102,7 +102,7 @@ This implementation:
This service 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 suppressed either using security or by implementing a xref:ug:btb:hints-and-tips/vetoing-visibility.adoc[vetoing subscriber].
+If contributions are not required in the UI, these can be suppressed either using security or by implementing a xref:ug:btb:about.adoc#vetoing-visibility[vetoing subscriber].
diff --git a/core/_adoc-rg/modules/svc/pages/presentation-layer-spi/TranslationService.adoc b/core/_adoc-rg/modules/svc/pages/presentation-layer-spi/TranslationService.adoc
index a0aa108..028cdaa 100644
--- a/core/_adoc-rg/modules/svc/pages/presentation-layer-spi/TranslationService.adoc
+++ b/core/_adoc-rg/modules/svc/pages/presentation-layer-spi/TranslationService.adoc
@@ -54,12 +54,12 @@ It relies on the `LocaleProvider` service (to return the `Locale` of the current
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.
-If the menu items are not required then these can be suppressed either using security or by implementing a xref:ug:btb:hints-and-tips/vetoing-visibility.adoc[vetoing subscriber].
+If the menu items are not required then these can be suppressed either using security or by implementing a xref:ug:btb:about.adoc#vetoing-visibility[vetoing subscriber].
For more details on the implementation, see xref:ug:btb:i18n.adoc[i18n support].
-If the menu items are not required then these can be suppressed either using security or by implementing a xref:ug:btb:hints-and-tips/vetoing-visibility.adoc[vetoing subscriber].
+If the menu items are not required then these can be suppressed either using security or by implementing a xref:ug:btb:about.adoc#vetoing-visibility[vetoing subscriber].
=== Configuration Properties
diff --git a/core/_adoc-ug/modules/btb/nav.adoc b/core/_adoc-ug/modules/btb/nav.adoc
index 07d0eac..25d56d5 100644
--- a/core/_adoc-ug/modules/btb/nav.adoc
+++ b/core/_adoc-ug/modules/btb/nav.adoc
@@ -9,18 +9,6 @@
** xref:hints-and-tips.adoc[Hints-n-Tips]
-*** xref:hints-and-tips/are-you-sure.adoc[Are you Sure]
-*** xref:hints-and-tips/replacing-default-service-implementations.adoc[Replacing Default Service Implementations]
-*** xref:hints-and-tips/vetoing-visibility.adoc[Vetoing Visibility]
-*** xref:hints-and-tips/transactions-and-errors.adoc[Transactions and Errors]
-*** xref:hints-and-tips/persisted-title.adoc[Persisted Title]
-*** xref:hints-and-tips/view-model-instantiation.adoc[View Model Instantiation]
-*** xref:hints-and-tips/simulating-collections-of-values.adoc[Simulating Collections of Values]
-*** xref:hints-and-tips/how-to-handle-void-and-null-results.adoc[How to handle void and null results]
-*** xref:hints-and-tips/multi-tenancy.adoc[Multi-tenancy]
-*** xref:hints-and-tips/subclass-properties-in-tables.adoc[Subclass properties in tables]
-*** xref:hints-and-tips/pushing-changes.adoc[Pushing Changes]
-*** xref:hints-and-tips/how-to-implement-a-spellchecker.adoc[How to implement a spellchecker]
** xref:programming-model.adoc[Programming Model]
diff --git a/core/_adoc-ug/modules/btb/pages/about.adoc b/core/_adoc-ug/modules/btb/pages/about.adoc
index 4ecd53a..52482b3 100644
--- a/core/_adoc-ug/modules/btb/pages/about.adoc
+++ b/core/_adoc-ug/modules/btb/pages/about.adoc
@@ -1,5 +1,6 @@
= Beyond the Basics
include::_attributes.adoc[]
+:page-partial:
This guide provides xref:ug:btb:other-techniques.adoc[more advanced] guidance on writing maintainable larger
diff --git a/core/_adoc-ug/modules/btb/pages/deployment.adoc b/core/_adoc-ug/modules/btb/pages/deployment.adoc
index 88f7742..8ef7407 100644
--- a/core/_adoc-ug/modules/btb/pages/deployment.adoc
+++ b/core/_adoc-ug/modules/btb/pages/deployment.adoc
@@ -1,6 +1,8 @@
+[[deployment]]
= Deployment
: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 ag [...]
include::_attributes.adoc[]
+:page-partial:
This chapter provides guidance on some common deployment scenarios.
diff --git a/core/_adoc-ug/modules/btb/pages/deployment/cmd-line.adoc b/core/_adoc-ug/modules/btb/pages/deployment/cmd-line.adoc
index b9c7c25..c4efc24 100644
--- a/core/_adoc-ug/modules/btb/pages/deployment/cmd-line.adoc
+++ b/core/_adoc-ug/modules/btb/pages/deployment/cmd-line.adoc
@@ -1,10 +1,16 @@
+[[cmd-line]]
= Command Line (`WebServer`)
: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 ag [...]
include::_attributes.adoc[]
+:page-partial:
-As well as deploying an Apache Isis application into a servlet container, it is also possible to invoke from the command line using the `org.apache.isis.WebServer` utility class. This is especially useful while developing and testing, but may also suit some deployment scenarios (eg running as a standalone EXE within a Docker container, for example). Internally the `WebServer` spins up a Jetty servlet container.
+TODO: this is out-of-date, can instead use Spring container.
+
+As well as deploying an Apache Isis application into a servlet container, it is also possible to invoke from the command line using the `org.apache.isis.WebServer` utility class.
+This is especially useful while developing and testing, but may also suit some deployment scenarios (eg running as a standalone EXE within a Docker container, for example).
+Internally the `WebServer` spins up a Jetty servlet container.
The class also supports a number of command line arguments:
diff --git a/core/_adoc-ug/modules/btb/pages/deployment/docker.adoc b/core/_adoc-ug/modules/btb/pages/deployment/docker.adoc
index 695e8ee..e931f8d 100644
--- a/core/_adoc-ug/modules/btb/pages/deployment/docker.adoc
+++ b/core/_adoc-ug/modules/btb/pages/deployment/docker.adoc
@@ -1,6 +1,8 @@
+[[docker]]
= Docker
: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 ag [...]
include::_attributes.adoc[]
+:page-partial:
When running the application within a Docker container, the problem that must be solved is to override the
diff --git a/core/_adoc-ug/modules/btb/pages/deployment/externalized-configuration.adoc b/core/_adoc-ug/modules/btb/pages/deployment/externalized-configuration.adoc
index 1f44e9c..c6c37c6 100644
--- a/core/_adoc-ug/modules/btb/pages/deployment/externalized-configuration.adoc
+++ b/core/_adoc-ug/modules/btb/pages/deployment/externalized-configuration.adoc
@@ -1,6 +1,8 @@
- = Externalized Configuration
+[[externalized-configuration]]
+= Externalized Configuration
:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...]
include::_attributes.adoc[]
+:page-partial:
@@ -13,7 +15,7 @@ It's generally not good practice to have the same configuration property in more
[TIP]
====
In addition the framework will also load the `overrides.properties` file.
-This is intended to support deployment through Docker, as discussed xref:ug:btb:deployment/docker.adoc[next].
+This is intended to support deployment through Docker, as discussed xref:ug:btb:about.adoc#docker[next].
====
All of these files are read from the `WEB-INF` directory.
@@ -34,7 +36,7 @@ Each of these frameworks has its own way of externalizing its configuration.
[TIP]
====
-Subsequent sections explain how to externalize configuration for xref:ug:btb:deployment/tomcat.adoc[Tomcat] and for xref:ug:btb:deployment/docker.adoc[Docker].
+Subsequent sections explain how to externalize configuration for xref:ug:btb:about.adoc#docker[Docker].
====
diff --git a/core/_adoc-ug/modules/btb/pages/deployment/gae.adoc b/core/_adoc-ug/modules/btb/pages/deployment/gae.adoc
index 719fcc2..5d76b12 100644
--- a/core/_adoc-ug/modules/btb/pages/deployment/gae.adoc
+++ b/core/_adoc-ug/modules/btb/pages/deployment/gae.adoc
@@ -1,6 +1,8 @@
+[[gae]]
= Deploying to Google App Engine
: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 ag [...]
include::_attributes.adoc[]
+:page-partial:
The link:https://cloud.google.com/appengine/docs[Google App Engine] (GAE) provides a JDO API, meaning that you can deploy Apache Isis onto GAE using the JDO objectstore.
diff --git a/core/_adoc-ug/modules/btb/pages/deployment/jvm-flags.adoc b/core/_adoc-ug/modules/btb/pages/deployment/jvm-flags.adoc
index 54359e7..00f4a49 100644
--- a/core/_adoc-ug/modules/btb/pages/deployment/jvm-flags.adoc
+++ b/core/_adoc-ug/modules/btb/pages/deployment/jvm-flags.adoc
@@ -1,6 +1,8 @@
+[[jvm-flags]]
= JVM Flags
: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 ag [...]
include::_attributes.adoc[]
+:page-partial:
NOTE: FIXME
diff --git a/core/_adoc-ug/modules/btb/pages/deployment/neo4j.adoc b/core/_adoc-ug/modules/btb/pages/deployment/neo4j.adoc
index 7a2dcf3..0008653 100644
--- a/core/_adoc-ug/modules/btb/pages/deployment/neo4j.adoc
+++ b/core/_adoc-ug/modules/btb/pages/deployment/neo4j.adoc
@@ -1,6 +1,8 @@
+[[neo4j]]
= Neo4J
: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 ag [...]
include::_attributes.adoc[]
+:page-partial:
Apache Isis has experimental support for Neo4J, courtesy of DataNucleus' http://www.datanucleus.org/products/datanucleus/datastores/neo4j.html[Neo4J Datastore] implementation.
diff --git a/core/_adoc-ug/modules/btb/pages/deployment/tomcat.adoc b/core/_adoc-ug/modules/btb/pages/deployment/tomcat.adoc
index e55e40d..37249d4 100644
--- a/core/_adoc-ug/modules/btb/pages/deployment/tomcat.adoc
+++ b/core/_adoc-ug/modules/btb/pages/deployment/tomcat.adoc
@@ -1,9 +1,11 @@
+[[tomcat]]
= Deploying to Tomcat
: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 ag [...]
include::_attributes.adoc[]
+:page-partial:
-Some pointers on how to xref:ug:btb:deployment/externalized-configuration.adoc[externalize configuration] when deploying to Tomcat.
+Some pointers on how to xref:ug:btb:about.adoc#externalized-configuration[externalize configuration] when deploying to Tomcat.
Other servlet containers have similar mechanisms.
diff --git a/core/_adoc-ug/modules/btb/pages/headless-access.adoc b/core/_adoc-ug/modules/btb/pages/headless-access.adoc
index 9598d25..a203aea 100644
--- a/core/_adoc-ug/modules/btb/pages/headless-access.adoc
+++ b/core/_adoc-ug/modules/btb/pages/headless-access.adoc
@@ -1,6 +1,8 @@
+[[headless-access]]
= Headless access
: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 ag [...]
include::_attributes.adoc[]
+:page-partial:
This section tackles the topic of enabling access to an Apache Isis application directly, or at least, not through either the xref:vw:ROOT:about.adoc[Wicket] or xref:vro:ROOT:about.adoc[Restful] viewers.
diff --git a/core/_adoc-ug/modules/btb/pages/headless-access/AbstractIsisSessionTemplate.adoc b/core/_adoc-ug/modules/btb/pages/headless-access/AbstractIsisSessionTemplate.adoc
index bcb4716..f773dc3 100644
--- a/core/_adoc-ug/modules/btb/pages/headless-access/AbstractIsisSessionTemplate.adoc
+++ b/core/_adoc-ug/modules/btb/pages/headless-access/AbstractIsisSessionTemplate.adoc
@@ -1,6 +1,8 @@
+[[AbstractIsisSessionTemplate]]
= AbstractIsisSessionTemplate
: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 ag [...]
include::_attributes.adoc[]
+:page-partial:
The `AbstractIsisSessionTemplate` class (whose name is inspired by the Spring framework's naming convention for similar classes that query http://docs.spring.io/spring/docs/2.5.x/reference/jdbc.html#jdbc-JdbcTemplate[JDBC], http://docs.spring.io/spring/docs/2.5.x/reference/jms.html#jms-jmstemplate[JMS], http://docs.spring.io/spring/docs/2.5.x/reference/orm.html#orm-jpa-template[JPA] etc.) provides the mechanism to open up a 'session' within the Apache Isis framework, in order to resolve [...]
diff --git a/core/_adoc-ug/modules/btb/pages/headless-access/BackgroundCommandExecution.adoc b/core/_adoc-ug/modules/btb/pages/headless-access/BackgroundCommandExecution.adoc
index 6dcf3c3..1548a34 100644
--- a/core/_adoc-ug/modules/btb/pages/headless-access/BackgroundCommandExecution.adoc
+++ b/core/_adoc-ug/modules/btb/pages/headless-access/BackgroundCommandExecution.adoc
@@ -1,10 +1,12 @@
+[[BackgroundCommandExecution]]
= BackgroundCommandExecution
: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 ag [...]
include::_attributes.adoc[]
+:page-partial:
-The `BackgroundCommandExecution` class (a subclass of xref:ug:btb:headless-access/AbstractIsisSessionTemplate.adoc[AbstractIsisSessionTemplate]) is intended to simplify the execution of background ``Command``s persisted by way of the xref:rg:svc:application-layer-spi/CommandService.adoc[`CommandService`] and the xref:rg:svc:application-layer-spi/BackgroundCommandService.adoc[`BackgroundCommandService`].
+The `BackgroundCommandExecution` class (a subclass of xref:ug:btb:about.adoc#BackgroundCommandService[`BackgroundCommandService`].
Its signature is:
diff --git a/core/_adoc-ug/modules/btb/pages/hints-and-tips.adoc b/core/_adoc-ug/modules/btb/pages/hints-and-tips.adoc
index fdbf21a..4ead8d2 100644
--- a/core/_adoc-ug/modules/btb/pages/hints-and-tips.adoc
+++ b/core/_adoc-ug/modules/btb/pages/hints-and-tips.adoc
@@ -2,23 +2,23 @@
= 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 ag [...]
include::_attributes.adoc[]
+:page-partial:
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:toc:devguide:hints-and-tips.adoc[Developers'] guide
-
-* the xref:vw:ROOT:hints-and-tips.adoc[Wicket viewer] guide
-
-* the xref:vro:ROOT:hints-and-tips.adoc[Restful Objects viewer] guide
-
-* the xref:odn:ROOT:hints-and-tips.adoc[Datanucleus ObjectStore] guide
-
-* the xref:security:ROOT:hints-and-tips.adoc[Security] guide
-
-* the xref:ug:btb:hints-and-tips.adoc[Beyond the Basics] guide (this chapter).
+include::hints-and-tips/are-you-sure.adoc[leveloffset=+1]
+include::hints-and-tips/replacing-default-service-implementations.adoc[leveloffset=+1]
+include::hints-and-tips/vetoing-visibility.adoc[leveloffset=+1]
+include::hints-and-tips/transactions-and-errors.adoc[leveloffset=+1]
+include::hints-and-tips/persisted-title.adoc[leveloffset=+1]
+include::hints-and-tips/view-model-instantiation.adoc[leveloffset=+1]
+include::hints-and-tips/simulating-collections-of-values.adoc[leveloffset=+1]
+include::hints-and-tips/how-to-handle-void-and-null-results.adoc[leveloffset=+1]
+include::hints-and-tips/multi-tenancy.adoc[leveloffset=+1]
+include::hints-and-tips/subclass-properties-in-tables.adoc[leveloffset=+1
+include::hints-and-tips/pushing-changes.adoc[leveloffset=+1]
+include::hints-and-tips/how-to-implement-a-spellchecker.adoc[leveloffset=+1]
diff --git a/core/_adoc-ug/modules/btb/pages/hints-and-tips/are-you-sure.adoc b/core/_adoc-ug/modules/btb/pages/hints-and-tips/are-you-sure.adoc
index 8ac5205..87b602d 100644
--- a/core/_adoc-ug/modules/btb/pages/hints-and-tips/are-you-sure.adoc
+++ b/core/_adoc-ug/modules/btb/pages/hints-and-tips/are-you-sure.adoc
@@ -1,6 +1,8 @@
-include::_attributes.adoc[]
+[[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 ag [...]
+include::_attributes.adoc[]
+:page-partial:
Sometimes an action might perform irreversible changes.
diff --git a/core/_adoc-ug/modules/btb/pages/hints-and-tips/how-to-handle-void-and-null-results.adoc b/core/_adoc-ug/modules/btb/pages/hints-and-tips/how-to-handle-void-and-null-results.adoc
index cde8689..77f7697 100644
--- a/core/_adoc-ug/modules/btb/pages/hints-and-tips/how-to-handle-void-and-null-results.adoc
+++ b/core/_adoc-ug/modules/btb/pages/hints-and-tips/how-to-handle-void-and-null-results.adoc
@@ -1,6 +1,8 @@
-include::_attributes.adoc[]
+[[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 ag [...]
+include::_attributes.adoc[]
+:page-partial:
diff --git a/core/_adoc-ug/modules/btb/pages/hints-and-tips/how-to-implement-a-spellchecker.adoc b/core/_adoc-ug/modules/btb/pages/hints-and-tips/how-to-implement-a-spellchecker.adoc
index 5e24a61..772a14e 100644
--- a/core/_adoc-ug/modules/btb/pages/hints-and-tips/how-to-implement-a-spellchecker.adoc
+++ b/core/_adoc-ug/modules/btb/pages/hints-and-tips/how-to-implement-a-spellchecker.adoc
@@ -1,6 +1,8 @@
-include::_attributes.adoc[]
+[[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 ag [...]
+include::_attributes.adoc[]
+:page-partial:
diff --git a/core/_adoc-ug/modules/btb/pages/hints-and-tips/multi-tenancy.adoc b/core/_adoc-ug/modules/btb/pages/hints-and-tips/multi-tenancy.adoc
index f0b153e..0f26349 100644
--- a/core/_adoc-ug/modules/btb/pages/hints-and-tips/multi-tenancy.adoc
+++ b/core/_adoc-ug/modules/btb/pages/hints-and-tips/multi-tenancy.adoc
@@ -1,6 +1,8 @@
-include::_attributes.adoc[]
+[[multi-tenancy]]
= Multi-tenancy
: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 ag [...]
+include::_attributes.adoc[]
+:page-partial:
Of the various modules provided by the (non-ASF) link:https://platform.incode.org[Incode Platform^], the security module has the most features.
diff --git a/core/_adoc-ug/modules/btb/pages/hints-and-tips/persisted-title.adoc b/core/_adoc-ug/modules/btb/pages/hints-and-tips/persisted-title.adoc
index b16de3c..40b9338 100644
--- a/core/_adoc-ug/modules/btb/pages/hints-and-tips/persisted-title.adoc
+++ b/core/_adoc-ug/modules/btb/pages/hints-and-tips/persisted-title.adoc
@@ -1,6 +1,8 @@
-include::_attributes.adoc[]
+[[persisted-title]]
= Persisted Title
: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 ag [...]
+include::_attributes.adoc[]
+:page-partial:
diff --git a/core/_adoc-ug/modules/btb/pages/hints-and-tips/pushing-changes.adoc b/core/_adoc-ug/modules/btb/pages/hints-and-tips/pushing-changes.adoc
index 4d8c34b..fb4056b 100644
--- a/core/_adoc-ug/modules/btb/pages/hints-and-tips/pushing-changes.adoc
+++ b/core/_adoc-ug/modules/btb/pages/hints-and-tips/pushing-changes.adoc
@@ -1,6 +1,8 @@
-include::_attributes.adoc[]
+[[pushing-changes]]
= Pushing Changes (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 ag [...]
+include::_attributes.adoc[]
+:page-partial:
[NOTE]
diff --git a/core/_adoc-ug/modules/btb/pages/hints-and-tips/replacing-default-service-implementations.adoc b/core/_adoc-ug/modules/btb/pages/hints-and-tips/replacing-default-service-implementations.adoc
index 431479f..ecef27b 100644
--- a/core/_adoc-ug/modules/btb/pages/hints-and-tips/replacing-default-service-implementations.adoc
+++ b/core/_adoc-ug/modules/btb/pages/hints-and-tips/replacing-default-service-implementations.adoc
@@ -1,6 +1,8 @@
-include::_attributes.adoc[]
+[[replacing-default-service-implementations]]
= Overriding Default Service Implns
: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 ag [...]
+include::_attributes.adoc[]
+:page-partial:
diff --git a/core/_adoc-ug/modules/btb/pages/hints-and-tips/simulating-collections-of-values.adoc b/core/_adoc-ug/modules/btb/pages/hints-and-tips/simulating-collections-of-values.adoc
index c981166..19ee440 100644
--- a/core/_adoc-ug/modules/btb/pages/hints-and-tips/simulating-collections-of-values.adoc
+++ b/core/_adoc-ug/modules/btb/pages/hints-and-tips/simulating-collections-of-values.adoc
@@ -1,6 +1,8 @@
-include::_attributes.adoc[]
+[[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 ag [...]
+include::_attributes.adoc[]
+:page-partial:
diff --git a/core/_adoc-ug/modules/btb/pages/hints-and-tips/subclass-properties-in-tables.adoc b/core/_adoc-ug/modules/btb/pages/hints-and-tips/subclass-properties-in-tables.adoc
index 7476646..a96c2bd 100644
--- a/core/_adoc-ug/modules/btb/pages/hints-and-tips/subclass-properties-in-tables.adoc
+++ b/core/_adoc-ug/modules/btb/pages/hints-and-tips/subclass-properties-in-tables.adoc
@@ -1,6 +1,8 @@
-include::_attributes.adoc[]
+[[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 ag [...]
+include::_attributes.adoc[]
+:page-partial:
diff --git a/core/_adoc-ug/modules/btb/pages/hints-and-tips/transactions-and-errors.adoc b/core/_adoc-ug/modules/btb/pages/hints-and-tips/transactions-and-errors.adoc
index 97e5d7d..b13a54b 100644
--- a/core/_adoc-ug/modules/btb/pages/hints-and-tips/transactions-and-errors.adoc
+++ b/core/_adoc-ug/modules/btb/pages/hints-and-tips/transactions-and-errors.adoc
@@ -1,6 +1,8 @@
-include::_attributes.adoc[]
+[[transactions-and-errors]]
= Transactions and Errors
: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 ag [...]
+include::_attributes.adoc[]
+:page-partial:
In Apache Isis, every interaction (action invocation or property edit) is automatically wrapped in a transaction,
and any repository query automatically does a flush before hand.
diff --git a/core/_adoc-ug/modules/btb/pages/hints-and-tips/vetoing-visibility.adoc b/core/_adoc-ug/modules/btb/pages/hints-and-tips/vetoing-visibility.adoc
index b37084e..1ffc822 100644
--- a/core/_adoc-ug/modules/btb/pages/hints-and-tips/vetoing-visibility.adoc
+++ b/core/_adoc-ug/modules/btb/pages/hints-and-tips/vetoing-visibility.adoc
@@ -1,6 +1,8 @@
-include::_attributes.adoc[]
+[[vetoing-visibility]]
= Vetoing Visibility
: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 ag [...]
+include::_attributes.adoc[]
+:page-partial:
NOTE: FIXME - a write-up of the "vetoing subscriber" design pattern, eg as described in the xref:rg:svc:integration-api/BookmarkService.adoc[`BookmarkService`]
diff --git a/core/_adoc-ug/modules/btb/pages/hints-and-tips/view-model-instantiation.adoc b/core/_adoc-ug/modules/btb/pages/hints-and-tips/view-model-instantiation.adoc
index 10f4402..5566b3b 100644
--- a/core/_adoc-ug/modules/btb/pages/hints-and-tips/view-model-instantiation.adoc
+++ b/core/_adoc-ug/modules/btb/pages/hints-and-tips/view-model-instantiation.adoc
@@ -1,6 +1,8 @@
-include::_attributes.adoc[]
+[[view-model-instantiation]]
= View Model Instantiation
: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 ag [...]
+include::_attributes.adoc[]
+:page-partial:
Vith view models, some care must be taken in how they are instantiated.
diff --git a/core/_adoc-ug/modules/btb/pages/i18n.adoc b/core/_adoc-ug/modules/btb/pages/i18n.adoc
index 52cfc7c..857aac5 100644
--- a/core/_adoc-ug/modules/btb/pages/i18n.adoc
+++ b/core/_adoc-ug/modules/btb/pages/i18n.adoc
@@ -1,6 +1,8 @@
+[[i18n]]
= i18n
: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 ag [...]
include::_attributes.adoc[]
+:page-partial:
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.
@@ -617,7 +619,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:ug:btb:deployment/externalized-configuration.adoc[external directory]; this is also supported for translations.
+However, Apache Isis can be configured to read config files from an xref:ug:btb:about.adoc#externalized-configuration[external directory]; this is also supported for translations.
Thus, if in `web.xml` the external configuration directory has been set:
diff --git a/core/_adoc-ug/modules/btb/pages/other-techniques.adoc b/core/_adoc-ug/modules/btb/pages/other-techniques.adoc
index ae220f3..69113a1 100644
--- a/core/_adoc-ug/modules/btb/pages/other-techniques.adoc
+++ b/core/_adoc-ug/modules/btb/pages/other-techniques.adoc
@@ -1,6 +1,8 @@
+[[other-techniques]]
= Other Techniques
: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 ag [...]
include::_attributes.adoc[]
+:page-partial:
diff --git a/core/_adoc-ug/modules/btb/pages/programming-model.adoc b/core/_adoc-ug/modules/btb/pages/programming-model.adoc
index 3ed91b6..5da8ef8 100644
--- a/core/_adoc-ug/modules/btb/pages/programming-model.adoc
+++ b/core/_adoc-ug/modules/btb/pages/programming-model.adoc
@@ -1,6 +1,8 @@
+[[programming-model]]
= Customizing the Prog 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 ag [...]
include::_attributes.adoc[]
+:page-partial:
This chapter explains the main APIs to extend or alter the programming conventions that Apache Isis understands to
diff --git a/core/_adoc-ug/modules/btb/pages/programming-model/custom-validator.adoc b/core/_adoc-ug/modules/btb/pages/programming-model/custom-validator.adoc
index 2868313..fdfeb99 100644
--- a/core/_adoc-ug/modules/btb/pages/programming-model/custom-validator.adoc
+++ b/core/_adoc-ug/modules/btb/pages/programming-model/custom-validator.adoc
@@ -1,6 +1,8 @@
+[[custom-validator]]
= Custom validator
: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 ag [...]
include::_attributes.adoc[]
+:page-partial:
Apache Isis' programming model includes a validator component that detects and prevents (by failing fast) a number of situations where the domain model is logically inconsistent.
diff --git a/core/_adoc-ug/modules/btb/pages/programming-model/finetuning.adoc b/core/_adoc-ug/modules/btb/pages/programming-model/finetuning.adoc
index b41a536..cc0fdc9 100644
--- a/core/_adoc-ug/modules/btb/pages/programming-model/finetuning.adoc
+++ b/core/_adoc-ug/modules/btb/pages/programming-model/finetuning.adoc
@@ -1,6 +1,8 @@
+[[finetuning]]
= Finetuning
: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 ag [...]
include::_attributes.adoc[]
+:page-partial:
The core metamodel defines APIs and implementations for building the Apache Isis metamodel: a description of the set of entities, domain services and values that make up the domain model.
@@ -58,7 +60,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:ug:btb:hints-and-tips/multi-tenancy.adoc[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:ug:btb:about.adoc#multi-tenancy[Multi-Tenancy] is now a better solution to that particular use-case.
====
diff --git a/core/_adoc-ug/modules/btb/pages/web-xml.adoc b/core/_adoc-ug/modules/btb/pages/web-xml.adoc
index bcb84fa..e02bded 100644
--- a/core/_adoc-ug/modules/btb/pages/web-xml.adoc
+++ b/core/_adoc-ug/modules/btb/pages/web-xml.adoc
@@ -1,6 +1,8 @@
+[[web-xml]]
= `web.xml`
:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...]
include::_attributes.adoc[]
+:page-partial:
// TODO: v2: a lot of this has changed, because we now use `WebModule_Xxx` instead of `web.xml`, ie set this stuff up programmatically.
diff --git a/core/_adoc-ug/modules/fun/.asciidoctorconfig b/core/_adoc-ug/modules/fun/.asciidoctorconfig
new file mode 100644
index 0000000..bad2980
--- /dev/null
+++ b/core/_adoc-ug/modules/fun/.asciidoctorconfig
@@ -0,0 +1,5 @@
+:experimental:
+:attachmentsdir: {asciidoctorconfigdir}/assets/attachments
+:examplesdir: {asciidoctorconfigdir}/examples
+:imagesdir: {asciidoctorconfigdir}/assets/images
+:partialsdir: {asciidoctorconfigdir}/partials
diff --git a/core/_adoc-ug/modules/fun/pages/core-concepts.adoc b/core/_adoc-ug/modules/fun/pages/core-concepts.adoc
index ead1c07..12625d9 100644
--- a/core/_adoc-ug/modules/fun/pages/core-concepts.adoc
+++ b/core/_adoc-ug/modules/fun/pages/core-concepts.adoc
@@ -10,28 +10,12 @@ We've also added some new insights and made sure the material we've used is rele
include::core-concepts/philosophy.adoc[leveloffset=+1]
-include::core-concepts/philosophy/domain-driven-design.adoc[leveloffset=+2]
-include::core-concepts/philosophy/naked-objects-pattern.adoc[leveloffset=+2]
-include::core-concepts/philosophy/hexagonal-architecture.adoc[leveloffset=+2]
-include::core-concepts/philosophy/aop.adoc[leveloffset=+2]
-// include::core-concepts/philosophy/dci.adoc[leveloffset=+2] // FIXME: incomplete
-include::core-concepts/philosophy/how-eases-ddd.adoc[leveloffset=+2]
include::core-concepts/principles.adoc[leveloffset=+1]
-include::core-concepts/principles/build-not-buy.adoc[leveloffset=+2]
-include::core-concepts/principles/for-the-long-term.adoc[leveloffset=+2]
-//include::core-concepts/principles/testable.adoc[leveloffset=+2] // FIXME: incomplete
-//include::core-concepts/principles/lego-blocks.adoc[leveloffset=+2] // FIXME: incomplete
-//include::core-concepts/principles/isis-itself.adoc[leveloffset=+2] // FIXME: incomplete
-//include::core-concepts/principles/isis-itself/full-stack-but-extensible.adoc[leveloffset=+3] // FIXME: incomplete
-//include::core-concepts/principles/isis-itself/focuses-on-its-usp.adoc[leveloffset=+3] // FIXME: incomplete
include::core-concepts/apache-isis-vs.adoc[leveloffset=+1]
-include::core-concepts/apache-isis-vs/mvc-server-side.adoc[leveloffset=+2]
-include::core-concepts/apache-isis-vs/cqrs.adoc[leveloffset=+2]
-include::core-concepts/apache-isis-vs/event-sourcing.adoc[leveloffset=+2]
include::core-concepts/deployment-options.adoc[leveloffset=+1]
diff --git a/core/_adoc-ug/modules/fun/pages/core-concepts/apache-isis-vs.adoc b/core/_adoc-ug/modules/fun/pages/core-concepts/apache-isis-vs.adoc
index efb3d71..15eb7683 100644
--- a/core/_adoc-ug/modules/fun/pages/core-concepts/apache-isis-vs.adoc
+++ b/core/_adoc-ug/modules/fun/pages/core-concepts/apache-isis-vs.adoc
@@ -8,3 +8,6 @@ Many other frameworks promise rapid application development and provide automati
+include::apache-isis-vs/mvc-server-side.adoc[leveloffset=+1]
+include::apache-isis-vs/cqrs.adoc[leveloffset=+1]
+include::apache-isis-vs/event-sourcing.adoc[leveloffset=+1]
diff --git a/core/_adoc-ug/modules/fun/pages/core-concepts/deployment-options.adoc b/core/_adoc-ug/modules/fun/pages/core-concepts/deployment-options.adoc
index b42695c..f9c2de5 100644
--- a/core/_adoc-ug/modules/fun/pages/core-concepts/deployment-options.adoc
+++ b/core/_adoc-ug/modules/fun/pages/core-concepts/deployment-options.adoc
@@ -65,11 +65,11 @@ Apache Isis' xref:vro:ROOT:about.adoc[RestfulObjects viewer] is an implementatio
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 +
+* 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
+For example, using Angular or some other RIA technology such as Flex or JavaFX
-* to enable integration between systems +
+* to enable integration between systems
+
REST is designed to be machine-readable, and so is an excellent choice for synchronous data interchange scenarios.
diff --git a/core/_adoc-ug/modules/fun/pages/core-concepts/philosophy.adoc b/core/_adoc-ug/modules/fun/pages/core-concepts/philosophy.adoc
index 95f7e66..82a7452 100644
--- a/core/_adoc-ug/modules/fun/pages/core-concepts/philosophy.adoc
+++ b/core/_adoc-ug/modules/fun/pages/core-concepts/philosophy.adoc
@@ -6,3 +6,9 @@ include::_attributes.adoc[]
This section describes some of the core ideas and architectural patterns upon which Apache Isis builds.
+include::philosophy/domain-driven-design.adoc[leveloffset=+1]
+include::philosophy/naked-objects-pattern.adoc[leveloffset=+1]
+include::philosophy/hexagonal-architecture.adoc[leveloffset=+1]
+include::philosophy/aop.adoc[leveloffset=+1]
+// include::philosophy/dci.adoc[leveloffset=+1] // FIXME: incomplete
+include::philosophy/how-eases-ddd.adoc[leveloffset=+1]
diff --git a/core/_adoc-ug/modules/fun/pages/core-concepts/philosophy/hexagonal-architecture.adoc b/core/_adoc-ug/modules/fun/pages/core-concepts/philosophy/hexagonal-architecture.adoc
index 39b3ac0..7ad77f2 100644
--- a/core/_adoc-ug/modules/fun/pages/core-concepts/philosophy/hexagonal-architecture.adoc
+++ b/core/_adoc-ug/modules/fun/pages/core-concepts/philosophy/hexagonal-architecture.adoc
@@ -1,6 +1,6 @@
= Hexagonal Architecture
: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 ag [...]
-include::_attributes.adoc[]
+//include::_attributes.adoc[]
:page-partial:
diff --git a/core/_adoc-ug/modules/fun/pages/core-concepts/principles.adoc b/core/_adoc-ug/modules/fun/pages/core-concepts/principles.adoc
index f682a8a..a54e04c 100644
--- a/core/_adoc-ug/modules/fun/pages/core-concepts/principles.adoc
+++ b/core/_adoc-ug/modules/fun/pages/core-concepts/principles.adoc
@@ -14,3 +14,8 @@ This section describes some of the core principles and values that the framework
+include::principles/build-not-buy.adoc[leveloffset=+1]
+include::principles/for-the-long-term.adoc[leveloffset=+1]
+//include::principles/testable.adoc[leveloffset=+1] // FIXME: incomplete
+//include::principles/lego-blocks.adoc[leveloffset=+1] // FIXME: incomplete
+//include::principles/isis-itself.adoc[leveloffset=+1] // FIXME: incomplete
diff --git a/core/_adoc-ug/modules/fun/pages/core-concepts/principles/isis-itself.adoc b/core/_adoc-ug/modules/fun/pages/core-concepts/principles/isis-itself.adoc
index e1a3018..9612e05 100644
--- a/core/_adoc-ug/modules/fun/pages/core-concepts/principles/isis-itself.adoc
+++ b/core/_adoc-ug/modules/fun/pages/core-concepts/principles/isis-itself.adoc
@@ -7,3 +7,5 @@ include::_attributes.adoc[]
This section discusses some of the principles and values we apply to the development of the Apache Isis framework itself.
+//include::full-stack-but-extensible.adoc[leveloffset=+1] // FIXME: incomplete
+//include::focuses-on-its-usp.adoc[leveloffset=+1] // FIXME: incomplete
diff --git a/core/_adoc-ug/modules/fun/pages/programming-model/collections.adoc b/core/_adoc-ug/modules/fun/pages/programming-model/collections.adoc
index e6741f3..bbe9dc2 100644
--- a/core/_adoc-ug/modules/fun/pages/programming-model/collections.adoc
+++ b/core/_adoc-ug/modules/fun/pages/programming-model/collections.adoc
@@ -94,7 +94,7 @@ 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:ug:btb:hints-and-tips/simulating-collections-of-values.adoc[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:ug:btb:about.adoc#simulating-collections-of-values[elsewhere].
diff --git a/core/plugins/jdo/_adoc/modules/ROOT/pages/configuring.adoc b/core/plugins/jdo/_adoc/modules/ROOT/pages/configuring.adoc
index 8f2b9ab..6c7ce93 100644
--- a/core/plugins/jdo/_adoc/modules/ROOT/pages/configuring.adoc
+++ b/core/plugins/jdo/_adoc/modules/ROOT/pages/configuring.adoc
@@ -7,6 +7,6 @@ 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".
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:ug:btb:other-techniques/overriding-jdo-annotations.adoc[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:ug:btb:about.adoc#overriding-jdo-annotations[Overriding JDO Annotatons] for further discussion.
diff --git a/core/plugins/jdo/_adoc/modules/ROOT/pages/hints-and-tips.adoc b/core/plugins/jdo/_adoc/modules/ROOT/pages/hints-and-tips.adoc
index 756f26b..4de9310 100644
--- a/core/plugins/jdo/_adoc/modules/ROOT/pages/hints-and-tips.adoc
+++ b/core/plugins/jdo/_adoc/modules/ROOT/pages/hints-and-tips.adoc
@@ -6,19 +6,6 @@ include::_attributes.adoc[]
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:toc:devguide:hints-and-tips.adoc[Developers'] guide
-
-* the xref:vw:ROOT:hints-and-tips.adoc[Wicket viewer] guide
-
-* the xref:vro:ROOT:hints-and-tips.adoc[Restful Objects viewer] guide
-
-* the xref:odn:ROOT:hints-and-tips.adoc[Datanucleus ObjectStore] guide (this chapter)
-
-* the xref:security:ROOT:hints-and-tips.adoc[Security] guide
-
-* the xref:ug:btb:hints-and-tips.adoc[Beyond the Basics] guide.
diff --git a/core/security/_adoc/modules/ROOT/pages/hints-and-tips.adoc b/core/security/_adoc/modules/ROOT/pages/hints-and-tips.adoc
index 66fd43e..55c432e 100644
--- a/core/security/_adoc/modules/ROOT/pages/hints-and-tips.adoc
+++ b/core/security/_adoc/modules/ROOT/pages/hints-and-tips.adoc
@@ -8,19 +8,6 @@ include::_attributes.adoc[]
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:toc:devguide:hints-and-tips.adoc[Developers'] guide
-
-* the xref:vw:ROOT:hints-and-tips.adoc[Wicket viewer] guide
-
-* the xref:vro:ROOT:hints-and-tips.adoc[Restful Objects viewer] guide
-
-* the xref:odn:ROOT:hints-and-tips.adoc[Datanucleus ObjectStore] guide
-
-* the xref:security:ROOT:hints-and-tips.adoc[Security] guide (this chapter)
-
-* the xref:ug:btb:hints-and-tips.adoc[Beyond the Basics] guide.
diff --git a/core/testsupport/_adoc/modules/mvn/pages/validate.adoc b/core/testsupport/_adoc/modules/mvn/pages/validate.adoc
index 036fc11..c4ce2dc 100644
--- a/core/testsupport/_adoc/modules/mvn/pages/validate.adoc
+++ b/core/testsupport/_adoc/modules/mvn/pages/validate.adoc
@@ -158,7 +158,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:ug:btb:programming-model/custom-validator.adoc[here].
+It is also possible to customize the validation, explained xref:ug:btb:about.adoc#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:
diff --git a/core/viewer-restfulobjects/_adoc/modules/ROOT/pages/hints-and-tips.adoc b/core/viewer-restfulobjects/_adoc/modules/ROOT/pages/hints-and-tips.adoc
index cb91f45..3309e69 100644
--- a/core/viewer-restfulobjects/_adoc/modules/ROOT/pages/hints-and-tips.adoc
+++ b/core/viewer-restfulobjects/_adoc/modules/ROOT/pages/hints-and-tips.adoc
@@ -6,19 +6,6 @@ include::_attributes.adoc[]
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:toc:devguide:hints-and-tips.adoc[Developers'] guide
-
-* the xref:vw:ROOT:hints-and-tips.adoc[Wicket viewer] guide
-
-* the xref:vro:ROOT:hints-and-tips.adoc[Restful Objects viewer] guide (this chapter)
-
-* the xref:odn:ROOT:hints-and-tips.adoc[Datanucleus ObjectStore] guide
-
-* the xref:security:ROOT:hints-and-tips.adoc[Security] guide
-
-* the xref:ug:btb:hints-and-tips.adoc[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.
diff --git a/core/viewer-wicket/_adoc/modules/ROOT/pages/hints-and-tips.adoc b/core/viewer-wicket/_adoc/modules/ROOT/pages/hints-and-tips.adoc
index 5839fde..d91b82f 100644
--- a/core/viewer-wicket/_adoc/modules/ROOT/pages/hints-and-tips.adoc
+++ b/core/viewer-wicket/_adoc/modules/ROOT/pages/hints-and-tips.adoc
@@ -7,19 +7,6 @@ include::_attributes.adoc[]
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:toc:devguide:hints-and-tips.adoc[Developers'] guide
-
-* the xref:vw:ROOT:hints-and-tips.adoc[Wicket viewer] guide (this chapter)
-
-* the xref:vro:ROOT:hints-and-tips.adoc[Restful Objects viewer] guide
-
-* the xref:odn:ROOT:hints-and-tips.adoc[Datanucleus ObjectStore] guide
-
-* the xref:security:ROOT:hints-and-tips.adoc[Security] guide
-
-* the xref:ug:btb:hints-and-tips.adoc[Beyond the Basics] guide.