[03/51] [abbrv] isis git commit: ISIS-1133: working on anchors and cross-references.

[da...@apache.org]

ISIS-1133: working on anchors and cross-references.


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

Branch: refs/heads/master
Commit: 7db616ea11783853d6fc5371718fc4befeb35586
Parents: 570ae22
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Tue May 26 17:30:47 2015 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Tue May 26 17:30:47 2015 +0100

----------------------------------------------------------------------
 .../_ug_appendices_dev-env_eclipse.adoc         |   2 +-
 ...re-concepts_framework-provided-services.adoc |   2 +-
 ..._core-concepts_other-deployment-options.adoc |   4 +-
 .../_ug_core-concepts_philosophy_aop.adoc       |   8 +-
 ..._core-concepts_philosophy_how-eases-ddd.adoc |   2 +-
 ...ncepts_philosophy_naked-objects-pattern.adoc |  15 +-
 ...bjects-pattern_object-interface-mapping.adoc |  18 +
 ...core-concepts_principles_apache-isis-vs.adoc |  21 +-
 ...ts_principles_apache-isis-vs_metawidget.adoc |  15 +
 ...ache-isis-vs_mvc-server-side-frameworks.adoc |  19 +
 .../user-guide/_ug_deployment_neo4j.adoc        |   6 +-
 ...ding_programming-model_custom-validator.adoc |   2 +-
 ..._extending_programming-model_finetuning.adoc |   2 +-
 ...rogramming-model_layout-metadata-reader.adoc |   2 +-
 .../_ug_extending_restfulobjects-viewer.adoc    |   2 +-
 .../user-guide/_ug_extending_wicket-viewer.adoc |  10 +-
 ...ng_wicket-viewer_custom-bootstrap-theme.adoc |   2 +-
 .../user-guide/_ug_getting-started.adoc         |   8 +-
 ...ug_getting-started_datanucleus-enhancer.adoc |   8 +-
 ..._ug_getting-started_simpleapp-archetype.adoc |   6 +-
 .../user-guide/_ug_headless-access.adoc         |   2 +-
 .../user-guide/_ug_more-advanced_i18n.adoc      |   2 +-
 .../user-guide/_ug_restfulobjects-viewer.adoc   |   2 +-
 ...objects-viewer_configuration-properties.adoc |  72 +++
 ...configuration-properties_honor-ui-hints.adoc |  27 ++
 ...erties_simplified-object-representation.adoc |  68 +++
 ...uration-properties_suppressing-elements.adoc |  39 ++
 ...objects-viewer_configuration_properties.adoc | 182 --------
 ...s_disabling-persistence-by-reachability.adoc |   2 +-
 .../main/asciidoc/user-guide/_ug_security.adoc  |   2 +-
 ..._security_configuring-isis-to-use-shiro.adoc |   2 +-
 .../_ug_security_shiro-ini-realm.adoc           |   2 +-
 ...ng_bdd-spec-support_maven-configuration.adoc |   2 +-
 ...ing_bdd-spec-support_writing-a-bdd-spec.adoc |   6 +-
 ...g_testing_fixture-scripts_api-and-usage.adoc |  12 +-
 ...esting_integ-test-support_bootstrapping.adoc |   2 +-
 ..._integ-test-support_maven-configuration.adoc |   2 +-
 ...g_unit-test-support_maven-configuration.adoc |   2 +-
 .../_ug_troubleshooting_enabling-logging.adoc   |   2 +-
 .../user-guide/_ug_tutorials_pet-clinic.adoc    |   2 +-
 .../asciidoc/user-guide/_ug_wicket-viewer.adoc  |   2 +-
 ..._wicket-viewer_configuration-properties.adoc | 112 +++++
 ...guration-properties_abbreviating-titles.adoc |  33 ++
 ...ration-properties_showing-theme-chooser.adoc |  43 ++
 ...uration-properties_stripped-wicket-tags.adoc |  26 ++
 ...n-properties_suppressing-password-reset.adoc |  47 ++
 ...tion-properties_suppressing-remember-me.adoc |  35 ++
 ...guration-properties_suppressing-sign-up.adoc |  49 ++
 ..._wicket-viewer_configuration_properties.adoc | 277 -----------
 .../_ug_wicket-viewer_customisation.adoc        | 459 +------------------
 ..._wicket-viewer_customisation_about-page.adoc | 121 +++++
 ...icket-viewer_customisation_auto-refresh.adoc |  35 ++
 ..._wicket-viewer_customisation_brand-logo.adoc |  71 +++
 ...er_customisation_cheap-n-cheerful-theme.adoc |  29 ++
 ...-viewer_customisation_custom-javascript.adoc |  42 ++
 ...cket-viewer_customisation_default-theme.adoc |  29 ++
 ...ewer_customisation_tweaking-css-classes.adoc | 109 +++++
 ..._customisation_using-different-css-file.adoc |  36 ++
 ...icket-viewer_customisation_welcome-page.adoc |  42 ++
 59 files changed, 1191 insertions(+), 992 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/7db616ea/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_dev-env_eclipse.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_dev-env_eclipse.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_dev-env_eclipse.adoc
index acc4a6b..7c26664 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_dev-env_eclipse.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_dev-env_eclipse.adoc
@@ -59,7 +59,7 @@ image::{_imagesdir}appendices/dev-env/eclipse/eclipse-110-project-support.png[wi
 
 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:_datanucleus_enhancer[DataNucleus enhancer] for details of the contents of the `pom.xml`.  Chances are it is already set up from running the xref:__a_id_getting_started_a_simpleapp_archetype[SimpleApp archetype].
+See the earlier section on xref:_ug_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:_ug_getting-started_simpleapp-archetype[SimpleApp archetype].
 
 
 Then, tell DataNucleus to use the project classpath:

http://git-wip-us.apache.org/repos/asf/isis/blob/7db616ea/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_framework-provided-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_framework-provided-services.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_framework-provided-services.adoc
index 33b859b..566ac21 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_framework-provided-services.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_framework-provided-services.adoc
@@ -25,7 +25,7 @@ It is possible to replacing automatically-registered domain services.
 
 Unless indicated as SPI, each of the following has an implementation in Isis core.
 
-A full list of services (including those with implementations in http://isisaddons.org[Isis Addons] (non-ASF)) can be found in the xref:_domain_services_2[Domain Services] section.
+A full list of services (including those with implementations in http://isisaddons.org[Isis Addons] (non-ASF)) can be found in the xref:_ug_domain-services-spi[Domain Services (SPI)] chapter.
 
 ### `DomainObjectContainer`
 

http://git-wip-us.apache.org/repos/asf/isis/blob/7db616ea/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_other-deployment-options.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_other-deployment-options.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_other-deployment-options.adoc
index e0db903..bdd2b4b 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_other-deployment-options.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_other-deployment-options.adoc
@@ -18,7 +18,7 @@ Let's start though with the default use case for Isis: building line-of-business
 
 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:_add_ons[Isis addons], 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:_ug_isis-addons-modules[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 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 https://developers.google.com/appengine/[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 Isis deliberately minimizes the dependencies on the rest of the framework. In fact, the only hard dependency that the domain model classes have on Isis is through the `org.apache.isis.applib` classes, mostly to pick up annotations such as `@Disabled`.
 So, if you have used 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; 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 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 Isis provides "out-of-the-box" (eg xref:__code_queryresultscache_code[`QueryResultsCache`]).
+If you go this route, your deployment platform will of course need to provide similar capabilities to 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 Isis provides "out-of-the-box" (eg xref:_ug_reference-services-api_manpage-QueryResultsCache[`QueryResultsCache`] domain service).
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/7db616ea/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_philosophy_aop.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_philosophy_aop.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_philosophy_aop.adoc
index af80422..5b00515 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_philosophy_aop.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_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; and many tend to think of xref:_domain_driven_design,DDD>> as an updated treatise on good object modelling[in the same vein as Rebecca Wirf Brock's link:http://en.wikipedia.org/wiki/Responsibility-driven_design[Responsibility Driven Design], say.  Meanwhile the <<_naked_objects_pattern, naked objects pattern] very much comes from an OO background (it even has 'object' in its name); and Richard Pawson lists Alan Kay as a key influence.
+Although not a book about object modelling, Evans' "Domain Driven Design" does use object orientation as its primary modelling tool; and many tend to think of xref:_ug_core-concepts_philosophy_domain-driven-design,DDD>> as an updated treatise on good object modelling[in the same vein as Rebecca Wirf Brock's link:http://en.wikipedia.org/wiki/Responsibility-driven_design[Responsibility Driven Design], say.  Meanwhile the <<_naked_objects_pattern, naked objects pattern] very much comes from an OO background (it even has 'object' in its name); and Richard Pawson 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.  But given that all the mainstream languages for developing business systems are object oriented (Java, C#, Ruby), that's not such a stretch.
 
@@ -29,8 +29,8 @@ Isis also draws heavily on the AOP concept of interceptors.  Whenever an object
 
 Another example of interceptors are the http://github.com/isisaddons/isis-module-command}[Isis addons' command] and http://github.com/isisaddons/isis-module-audit}[Isis addons' audit] modules.  The command module captures every user interaction that modifies the state of the system (the "cause" of a change) while the audit module captures every change to every object (the "effect" of a change).  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 xref:_decoupling[Decoupling] chapter.  But fundamentally its relying on this AOP concept of interceptors.
+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:_ug_more-advanced_decoupling[Decoupling].  But fundamentally its relying on this AOP concept of interceptors.
 
-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:_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.  Isis' support for contributions (not only contributed actions, but also contributed properties and contributed collections) enables this.  And again, to loop back to the topic of this section, it's an AOP concept that bei
 ng implemented by the framework.
+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:_ug_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.  Isis' support for contributions (not only contributed actions, but also contributed properties and contributed collections) enables this.  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 Isis' AOP support for mixins (xref:_contributed_members[contributions]) and interceptors (the xref:_event_bus[event bus]) to ensure that your codebase remains maintainable.
\ No newline at end of file
+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 Isis' AOP support for mixins (xref:_ug_more-advanced_decoupling_contributions[contributions]) and interceptors (the xref:_ug_more-advanced_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/7db616ea/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_philosophy_how-eases-ddd.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_philosophy_how-eases-ddd.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_philosophy_how-eases-ddd.adoc
index 5a801d0..1e6f601 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_philosophy_how-eases-ddd.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_philosophy_how-eases-ddd.adoc
@@ -40,7 +40,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:_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:_ug_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/7db616ea/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_philosophy_naked-objects-pattern.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_philosophy_naked-objects-pattern.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_philosophy_naked-objects-pattern.adoc
index bc07fcd..6eea8da 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_philosophy_naked-objects-pattern.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_philosophy_naked-objects-pattern.adoc
@@ -38,18 +38,17 @@ Reenskaug then goes on to say that "this simple and powerful idea failed because
 In Apache Isis the responsibility of rendering an object is not the object itself, it is the framework.  Rather, the object inspects the object and uses that to decide how to render the object.  This is also extensible.  In the http://isisaddons.org[Isis Addons] (non-ASF) the http://github.com/isisaddons/isis-wicket-gmap3}[Isis addons' gmap3 modue] renders any object with latitude/longitude on a map, while http://github.com/isisaddons/isis-wicket-fullcalendar2}[Isis addons' fullcalendar2 wicket extension] renders any object with date(s) on a calendar.
 ====
 
-== Object Interface Mapping
 
-Another -- more technical -- way to think about the naked objects pattern is as an _object interface mapper_, or `OIM`.  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, specifically 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].
 
-[NOTE]
-====
-We compare Apache Isis' with MetaWidget xref:_vs_metawidget[here].
-====
+include::_ug_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping.adoc[leveloffset=+1]
+
+
+
+
+
+
 
 == What this means in practice
 

http://git-wip-us.apache.org/repos/asf/isis/blob/7db616ea/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping.adoc
new file mode 100644
index 0000000..2bf7467
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping.adoc
@@ -0,0 +1,18 @@
+[[_ug_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping]]
+= Object Interface Mapping
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the 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/
+
+
+Another -- more technical -- way to think about the naked objects pattern is as an _object interface mapper_, or `OIM`.  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, specifically 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].
+
+[NOTE]
+====
+We compare Apache Isis' with MetaWidget xref:_ug_core-concepts_principles_apache-isis-vs_metawidget[here].
+====
+

http://git-wip-us.apache.org/repos/asf/isis/blob/7db616ea/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_principles_apache-isis-vs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_principles_apache-isis-vs.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_principles_apache-isis-vs.adoc
index 8b07348..10d9ca9 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_principles_apache-isis-vs.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_principles_apache-isis-vs.adoc
@@ -8,18 +8,7 @@ Many other frameworks promise rapid application development and provide automati
 do they compare to Apache Isis?
 
 
-
-== vs MVC server-side frameworks
-
-Some of most commonly used frameworks today are link:http://www.springframework.org/[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 (scheduled for JavaEE 8) 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:_extending_the_viewer[extending Isis' Wicket viewer] or by writing a bespoke UI leveraging the REST (hypermedia) API automatically exposed by xref:_restful_objects_viewer[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 Isis' REST API.
-
-Although these frameworks all provide their own ecosystems of extensions, Isis' equivalent http://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. Isis' support is similar.  Where Isis differs though is that it enables end-to-end testing without the need for slow and fragile Selenium tests. Instead, Isis provides a "xref:_using_the_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.
+include::_ug_core-concepts_principles_apache-isis-vs_mvc-server-side-frameworks.adoc[leveloffset=+1]
 
 
 
@@ -35,15 +24,9 @@ In terms of testing support, each of these other frameworks provide mechanisms t
 
 
 
-== vs MetaWidget
-
-MetaWidget (mentioned xref:_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".  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 http://isisaddons.org[Isis Addons] (non-ASF), and we also provide a full xref:_restful_objects_viewer[Restful API]
+include::_ug_core-concepts_principles_apache-isis-vs_metawidget.adoc[leveloffset=+1]
 
-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 Isis' own metamodel as an implementation of the MetaWidget API.  This would allow MetaWidget to be able to render an Isis domain application.
 
 
 == vs OpenXava

http://git-wip-us.apache.org/repos/asf/isis/blob/7db616ea/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_principles_apache-isis-vs_metawidget.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_principles_apache-isis-vs_metawidget.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_principles_apache-isis-vs_metawidget.adoc
new file mode 100644
index 0000000..48b4a6b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_principles_apache-isis-vs_metawidget.adoc
@@ -0,0 +1,15 @@
+[[_ug_core-concepts_principles_apache-isis-vs_metawidget]]= vs MetaWidget
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the 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/
+
+
+MetaWidget (mentioned xref:_ug_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".  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 http://isisaddons.org[Isis Addons] (non-ASF), and we also provide a full REST API through the xref:_ug_restfulobjects-viewer[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 Isis' own metamodel as an implementation of the MetaWidget API.  This would allow MetaWidget to be able to render an Isis domain application.
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/7db616ea/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_principles_apache-isis-vs_mvc-server-side-frameworks.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_principles_apache-isis-vs_mvc-server-side-frameworks.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_principles_apache-isis-vs_mvc-server-side-frameworks.adoc
new file mode 100644
index 0000000..8bf15fe
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_principles_apache-isis-vs_mvc-server-side-frameworks.adoc
@@ -0,0 +1,19 @@
+[[_ug_core-concepts_principles_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.springframework.org/[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 (scheduled for JavaEE 8) 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:_ug_extending_wicket-viewer[extending Isis' Wicket viewer] or by writing a bespoke UI leveraging the REST (hypermedia) API automatically exposed by xref:_ug_restfulobjects-viewer[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 Isis' REST API.
+
+Although these frameworks all provide their own ecosystems of extensions, Isis' equivalent http://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. Isis' support is similar.  Where Isis differs though is that it enables end-to-end testing without the need for slow and fragile Selenium tests. Instead, Isis provides a "xref:_ug_testing_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/7db616ea/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment_neo4j.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment_neo4j.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment_neo4j.adoc
index baaeff4..53181bf 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment_neo4j.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_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:__a_id_getting_started_a_simpleapp_archetype[SimpleApp archetype] has been updated so that they can be optionally run under Neo4J.
+The xref:_ug_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 1.8.0, use the value shown.  for 1.9.0-SNAPSHOT, use 4.0.5.
 
-In the xref:__a_id_getting_started_a_simpleapp_archetype[SimpleApp archetype] this is defined under the "neo4j" profile so can be activated using `-P neo4j`.
+In the xref:_ug_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:__a_id_getting_started_a_simpleapp_archetype[SimpleApp archetype] (v1.8.0)
+* run the xref:_ug_getting-started_simpleapp-archetype[SimpleApp archetype] (v1.8.0)
 
 * build the app:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/7db616ea/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_programming-model_custom-validator.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_programming-model_custom-validator.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_programming-model_custom-validator.adoc
index c7fa8f2..a0c5ca8 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_programming-model_custom-validator.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_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:_isis_maven_plugin[Maven plugin] will also validate the domain object model during build time.
+Isis' xref:_ug_isis-maven-plugin[Maven plugin] will also validate the domain object model during build time.
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/7db616ea/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_programming-model_finetuning.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_programming-model_finetuning.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_programming-model_finetuning.adoc
index c2ab8af..31d737e 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_programming-model_finetuning.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_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:_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:_ug_more-advanced_multi-tenancy[Multi-Tenancy] is now a better solution to that particular use-case.
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/7db616ea/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_programming-model_layout-metadata-reader.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_programming-model_layout-metadata-reader.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_programming-model_layout-metadata-reader.adoc
index 8bd1183..5bb6d44 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_programming-model_layout-metadata-reader.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_programming-model_layout-metadata-reader.adoc
@@ -5,7 +5,7 @@
 :_imagesdir: images/
 
 
-The metadata for domain objects is obtained both xref:_static_object_layout[statically] and xref:_dynamic_object_layout[dynamically].
+The metadata for domain objects is obtained both xref:_ug_wicket-viewer_layout_static-object-layout[statically] and xref:_ug_wicket-viewer_layout_dynamic-object-layout[dynamically].
 
 The default implementation for reading dynamic layout metadata is `org.apache.isis.core.metamodel.layoutmetadata.json.LayoutMetadataReaderFromJson`, which is responsible for reading from the `Xxx.layout.json` files on the classpath (for each domain entity `Xxx`).
 

http://git-wip-us.apache.org/repos/asf/isis/blob/7db616ea/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_restfulobjects-viewer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_restfulobjects-viewer.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_restfulobjects-viewer.adoc
index c330ca9..4d176b8 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_restfulobjects-viewer.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_restfulobjects-viewer.adoc
@@ -27,7 +27,7 @@ it is possible to plugin a custom representation generator that can produce any
 
 [TIP]
 ====
-If all that is required is a very simple representations (of objects), you can instead reconfigure RO viewer to provide a simplified output, as described xref:_simplified_object_representation[here].  Or, it is also possible to simply suppress certain elements, as described  xref:_suppressing_elements_of_the_representations[here].
+If all that is required is a very simple representations (of objects), you can instead reconfigure RO viewer to provide a simplified output, as described xref:_ug_restfulobjects-viewer_configuration-properties_simplified-object-representation[here].  Or, it is also possible to simply suppress certain elements, as described  xref:_ug_restfulobjects-viewer_configuration-properties_suppressing-elements[here].
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/7db616ea/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_wicket-viewer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_wicket-viewer.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_wicket-viewer.adoc
index ddbe546..10e431e 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_wicket-viewer.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_wicket-viewer.adoc
@@ -7,11 +7,11 @@
 
 The Wicket viewer allows you to customize the GUI in several (progressively more sophisticated) ways:
 
-* by xref:_tweak_the_ui_with_css[tweaking the UI using CSS]
-* by xref:_tweak_the_ui_with_javascript[tweaking the UI using Javascript]
-* by writing a xref:_writing_a_custom_theme[custom bootstrap theme]
-* by xref:_replacing_page_elements[replacing elements of the page] using the `ComponentFactory` interface
-* by implementing xref:_custom_pages[replacement page implementations] for the standard page types
+* by xref:_ug_wicket-viewer_customisation_tweaking-css-classes[tweaking the UI using CSS]
+* by xref:_ug_wicket-viewer_customisation_custom-javascript[tweaking the UI using Javascript]
+* by writing a xref:_ug_extending_wicket-viewer_custom-bootstrap-theme[custom bootstrap theme]
+* by xref:_ug_extending_wicket-viewer_replacing-page-elements[replacing elements of the page] using the `ComponentFactory` interface
+* by implementing xref:_ug_extending_wicket-viewer_custom-pages[replacement page implementations] for the standard page types
 
 The first two of these options are discussed in the <<Wicket Viewer>> chapter.  This chapter describes the remaining "heavier-weight/more powerful" options.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/7db616ea/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_wicket-viewer_custom-bootstrap-theme.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_wicket-viewer_custom-bootstrap-theme.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_wicket-viewer_custom-bootstrap-theme.adoc
index 0e65a64..10def91 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_wicket-viewer_custom-bootstrap-theme.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_wicket-viewer_custom-bootstrap-theme.adoc
@@ -8,7 +8,7 @@
 
 The 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:_showing_a_theme_chooser[select other themes] provided by http://bootswatch.com[bootswatch.com], and if required one of these can be xref:_specifying_a_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:_ug_wicket-viewer_configuration-properties_showing-theme-chooser[select other themes] provided by http://bootswatch.com[bootswatch.com], and if required one of these can be xref:_ug_wicket-viewer_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]’s `de.agilecoders.wicket.core.settings.ITheme` class. This defines:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/7db616ea/adocs/documentation/src/main/asciidoc/user-guide/_ug_getting-started.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_getting-started.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_getting-started.adoc
index c641961..de30022 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_getting-started.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_getting-started.adoc
@@ -7,13 +7,13 @@
 
 
 
-To get you up and running quickly, Apache Isis provides a xref:_simpleapp_archetype[maven archetype] to setup a simple application as the basis of your own apps.  This is deliberately very 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.
+To get you up and running quickly, Apache Isis provides a xref:_ug_getting-started_simpleapp-archetype[SimpleApp archetype] to setup a simple application as the basis of your own apps.  This is deliberately very 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 DataNucleus xref:_datanucleus_enhancer[enhancer].  link:http://www.datanucleus.org/[DataNucleus] is the reference implementation of the JDO (Java data objects) spec, and 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 Isis' JDO/DataNucleus objectstore.
+In this chapter we also discuss the xref:_ug_getting-started_datanucleus-enhancer[DataNucleus enhancer].  link:http://www.datanucleus.org/[DataNucleus] is the reference implementation of the JDO (Java data objects) spec, and 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 Isis' JDO/DataNucleus objectstore.
 
 [NOTE]
 ====
-The xref:__a_id_getting_started_a_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 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.
+The xref:_ug_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 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.
 ====
 
 
@@ -26,7 +26,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 Isis committers use either IntelliJ or Eclipse; in the xref:_appendices[appendices] 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.
+You'll probably also want to use an IDE; the Isis committers use either IntelliJ or Eclipse; in the xref:_ug_appendices[appendices] 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.  This is implemented as a Maven plugin, so in the case of IntelliJ, it's easy enough to run the enhancer as required. It should be just as straightforward for NetBeans too.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/7db616ea/adocs/documentation/src/main/asciidoc/user-guide/_ug_getting-started_datanucleus-enhancer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_getting-started_datanucleus-enhancer.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_getting-started_datanucleus-enhancer.adoc
index 7bbbcf3..bf33ad6 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_getting-started_datanucleus-enhancer.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_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:__a_id_getting_started_a_simpleapp_archetype[SimpleApp archetype].
+The configuration described below is automatically set up by the xref:_ug_getting-started_simpleapp-archetype[SimpleApp archetype].
 ====
 
 
@@ -75,7 +75,7 @@ The configuration described below is automatically set up by the xref:__a_id_get
 </profile>
 ----
 
-The xref:__a_id_getting_started_a_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:_ug_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:__a_id_getting_started_a_simpleapp_archetype[SimpleApp archetype] does this.
+Again, the xref:_ug_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:_setting_up_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:_ug_appendices_dev-env_eclipse[here].
 ====

http://git-wip-us.apache.org/repos/asf/isis/blob/7db616ea/adocs/documentation/src/main/asciidoc/user-guide/_ug_getting-started_simpleapp-archetype.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_getting-started_simpleapp-archetype.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_getting-started_simpleapp-archetype.adoc
index b24eb07..1caa3b9 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_getting-started_simpleapp-archetype.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_getting-started_simpleapp-archetype.adoc
@@ -91,7 +91,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:_wicket_viewer[Wicket viewer] and the xref:_restful_objects_viewer[Restful Objects viewer].  The archetype also configures the [JDO Objectstore](../../components/objectstores/jdo/about.html) to use an in-memory HSQLDB connection.
+The `simpleapp` archetype generates a single WAR file, configured to run both the xref:_ug_wicket-viewer[Wicket viewer] and the xref:_ug_restfulobjects-viewer[Restful Objects viewer].  The archetype also configures the [JDO Objectstore](../../components/objectstores/jdo/about.html) to use an in-memory HSQLDB connection.
 
 Once you've built the app, you can run the WAR in a variety of ways.
 
@@ -147,7 +147,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 appendices for details on xref:_setting_up_eclipse[setting up Eclipse] or xref:_setting_up_intellij_idea[setting up IntelliJ IDEA].  Basically, though, it amounts to running `org.apache.isis.WebServer`, and ensuring that the xref:_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 appendices for details on xref:_ug_appendices_dev-env_eclipse[setting up Eclipse] or xref:_ug_appendices_dev-env_intellij[setting up IntelliJ IDEA].  Basically, though, it amounts to running `org.apache.isis.WebServer`, and ensuring that the xref:_ug_getting-started_datanucleus-enhancer[DataNucleus enhancer] has properly processed all domain entities.
 
 Here's what the setup looks like in IntelliJ IDEA:
 
@@ -179,7 +179,7 @@ image::{_imagesdir}getting-started/simpleapp-webapp-with-fixtures.png[width="600
 
 == Using the App
 
-When you start the app, you'll be presented with a welcome page from which you can access the webapp using either the xref:_wicket_viewer[Wicket viewer] or the xref:_restful_objects_viewer[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:_ug_wicket-viewer[Wicket viewer] or the xref:_ug_restfulobjects-viewer[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"]
 

http://git-wip-us.apache.org/repos/asf/isis/blob/7db616ea/adocs/documentation/src/main/asciidoc/user-guide/_ug_headless-access.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_headless-access.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_headless-access.adoc
index 9c1e88b..b4681f9 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_headless-access.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_headless-access.adoc
@@ -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 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:_restfulobjects_viewer[Restful Objects viewer] is usually the way to go.
+Note that the calling thread runs in the same process space as the 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:_ug_restfulobjects-viewer[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 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 <<WrapperFactory>> service could be used to enforce such business rules if required.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/7db616ea/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_i18n.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_i18n.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_i18n.adoc
index df63f27..d9deb3a 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_i18n.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_i18n.adoc
@@ -104,7 +104,7 @@ However, for an application to be fully internationalized, any validation messag
 
 The first part of the puzzle is tackled by an extension to 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:__a_id_getting_started_a_simpleapp_archetype[SimpleApp archetype]:
+Here's a (silly) example from the xref:_ug_getting-started_simpleapp-archetype[SimpleApp archetype]:
 
 [source,java]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/7db616ea/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer.adoc
index a35d9a1..53c894a 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer.adoc
@@ -12,7 +12,7 @@ The Restful Objects viewer also provides a number of proprietary extensions.
 
 include::_ug_restfulobjects-viewer_features.adoc[leveloffset=+1]
 
-include::_ug_restfulobjects-viewer_configuration_properties.adoc[leveloffset=+1]
+include::_ug_restfulobjects-viewer_configuration-properties.adoc[leveloffset=+1]
 
 include::_ug_restfulobjects-viewer_hints-and-tips.adoc[leveloffset=+1]
 

http://git-wip-us.apache.org/repos/asf/isis/blob/7db616ea/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties.adoc
new file mode 100644
index 0000000..6d9ec2d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties.adoc
@@ -0,0 +1,72 @@
+[[_ug_restfulobjects-viewer_configuration-properties]]
+= Configuration Properties
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+The Restful Objects viewer provides a number of configuration option that extend/simplify/alter the representations generated from the Restful Objects specification.
+
+These configuration properties are typically stored in `WEB-INF/viewer_restfulobjects.properties`.  However, you can place all configuration properties into `WEB-INF/isis.properties` if you wish (the configuration properties from all config files are merged together).
+
+[WARNING]
+====
+These configuration settings should be considered beta, and may change in the future in response to emerging requirements.
+
+Also, be aware enabling these settings makes the representations with respect to the http://restfulobjects.org[Restful Object spec].  (Based on experience in Isis, in the future the spec may be updated to allow such extensions).
+====
+
+
+.RestfulObjects Viewer Configuration Properties
+[cols="2a,1,3", options="header"]
+|===
+|Property
+|Value +
+(_default value_)
+|Description
+
+|`isis.viewer.restfulobjects.` +
+`honorUiHints`
+| `true`,`false` (`_false_`)
+| See xref:_honor_ui_hints[discussion], below.
+
+|`isis.viewer.restfulobjects.` +
+`suppressDescribedByLinks`
+| `true`,`false` (`_false_`)
+.6+| See xref:_suppressing_elements_of_the_representation[discussion], below.
+
+|`isis.viewer.restfulobjects.` +
+`suppressUpdateLink`
+| `true`,`false` (`_false_`)
+
+|`isis.viewer.restfulobjects.` +
+`suppressMemberId`
+| `true`,`false` (`_false_`)
+
+|`isis.viewer.restfulobjects.` +
+`suppressMemberLinks`
+| `true`,`false` (`_false_`)
+
+|`isis.viewer.restfulobjects.` +
+`suppressMemberExtensions`
+| `true`,`false` (`_false_`)
+
+|`isis.viewer.restfulobjects.` +
+`suppressMemberDisabledReason`
+| `true`,`false` (`_false_`)
+
+|`isis.viewer.restfulobjects.` +
+`objectPropertyValuesOnly`
+| `true`,`false` (`_false_`)
+| See xref:_simplified_object_representation[discussion], below.
+
+|===
+
+
+
+
+include::_ug_restfulobjects-viewer_configuration-properties_honor-ui-hints.adoc[leveloffset=+1]
+include::_ug_restfulobjects-viewer_configuration-properties_suppressing-elements.adoc[leveloffset=+1]
+include::_ug_restfulobjects-viewer_configuration-properties_simplified-object-representation.adoc[leveloffset=+1]
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/7db616ea/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties_honor-ui-hints.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties_honor-ui-hints.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties_honor-ui-hints.adoc
new file mode 100644
index 0000000..c9122cc
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties_honor-ui-hints.adoc
@@ -0,0 +1,27 @@
+[[_ug_restfulobjects-viewer_configuration-properties_honor-ui-hints]]
+= Honor 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/
+
+
+
+
+By default the representations generated by Restful Objects ignore any Isis metamodel hints referring to the UI.
+In particular, if a collection is annotated then `Render(EAGERLY)` then the contents of the collection are _not_
+eagerly embedded in the object representation.
+
+However, this behaviour can be overridden globally using following property (typically added to `WEB-INF/viewer_restfulobjects.properties`):
+
+[source,ini]
+----
+isis.viewer.restfulobjects.honorUiHints=true
+----
+
+[NOTE]
+====
+In the future we might extend this per-request.  Raise/vote on a JIRA ticket if you require this feature.
+====
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/7db616ea/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties_simplified-object-representation.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties_simplified-object-representation.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties_simplified-object-representation.adoc
new file mode 100644
index 0000000..120254a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties_simplified-object-representation.adoc
@@ -0,0 +1,68 @@
+[[_ug_restfulobjects-viewer_configuration-properties_simplified-object-representation]]
+= Simplified object representation
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the 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 representations specified by the http://restfulobjects.org[Restful Object spec] are very rich in hypermedia
+controls and metadata, intended to support a wide variety of possible REST clients.
+
+As described xref:_suppressing_elements_of_the_representations[above], it is possible to suppress various elements of these representations. Even then, though, the representations may be too complex for some bespoke REST clients that require a very "flat" object representation.
+
+The Restful Objects viewer therefore supports generating a much simpler representation of objects using the following configuration property (typically added to `WEB-INF/viewer_restfulobjects.properties`):
+
+[source,ini]
+----
+isis.viewer.restfulobjects.objectPropertyValuesOnly=true
+----
+
+This generates a representation such as:
+
+[source,javascript]
+----
+{
+    "title" : "Buy milk due by 2014-10-27",
+    "domainType" : "TODO",
+    "instanceId" : "0",
+    "members" : {
+        "description" : "Buy milk",
+        "category" : "Domestic",
+        "subcategory" : "Shopping",
+        "complete" : false,
+        "versionSequence" : 1,
+        "relativePriority" : 2,
+        "dueBy" : "2014-10-27",
+        "cost" : "0.75",
+        "notes" : null,
+        "attachment" : null,
+        "doc" : null
+    },
+    "links" : [
+        {
+            "rel" : "self",
+            "href" : "http://localhost:8080/restful/objects/TODO/0",
+            "method" : "GET",
+            "type" : "application/json;profile=\"urn:org.restfulobjects:repr-types/object\"",
+            "title" : "Buy milk due by 2014-10-27"
+        },
+        {
+            "rel" : "describedby",
+            "href" : "http://localhost:8080/restful/domain-types/TODO",
+            "method" : "GET",
+            "type" : "application/json;profile=\"urn:org.restfulobjects:repr-types/domain-type\""
+        }
+    ],
+    "extensions" : {
+        "oid" : "TODO:0"
+    },
+}
+----
+
+[NOTE]
+====
+In the future we might extend this per-request.  Raise/vote on a JIRA ticket if you require this feature.
+====
+
+If the above isn't flexible and you need complete control over all representations see the section on xref:_extending_the_restful_viewer[Extending the Restful viewer].

http://git-wip-us.apache.org/repos/asf/isis/blob/7db616ea/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties_suppressing-elements.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties_suppressing-elements.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties_suppressing-elements.adoc
new file mode 100644
index 0000000..d87ed17
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties_suppressing-elements.adoc
@@ -0,0 +1,39 @@
+[[_ug_restfulobjects-viewer_configuration-properties_suppressing-elements]]
+= Suppressing elements of the representation
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the 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 representations specified by the http://restfulobjects.org[Restful Object spec] are very rich in hypermedia controls and metadata, intended to support a wide variety of possible REST clients. However, if an application is providing its REST API only for a small well-defined set of REST clients, then it is possible to suppress (remove) various elements of these representations.
+
+This is done by globally using the following properties (typically added to `WEB-INF/viewer_restfulobjects.properties`):
+
+[source,ini]
+----
+isis.viewer.restfulobjects.suppressDescribedByLinks=true      # <1>
+isis.viewer.restfulobjects.suppressUpdateLink=true            # <2>
+isis.viewer.restfulobjects.suppressMemberId=true              # <3>
+isis.viewer.restfulobjects.suppressMemberLinks=true           # <4>
+isis.viewer.restfulobjects.suppressMemberExtensions=true      # <5>
+isis.viewer.restfulobjects.suppressMemberDisabledReason=true  # <6>
+----
+<1> suppresses the "describedby" links (on all representations)
+<2> suppresses the  "update" link (on object representation)
+<3> suppresses the  "id" json-prop for object members (on object representation and member detail representations)
+<4> suppresses the  "links" json-prop for object members (on the object representation and member detail representations)
+<5> suppresses the  "extensions" json-prop for object members (on the object representation and member detail representations)
+<6> suppresses the  "disabledReason" json-prop for object members (on the object representation and member detail representations)
+
+The defaults for all of these is false, meaning that the hypermedia/metadata is NOT suppressed.
+
+[NOTE]
+====
+In the future we might extend this per-request.  Raise/vote on a JIRA ticket if you require this feature.
+====
+
+If an even simpler representations (of objects) are required, see xref:_simplified_object_representation[simplified object representation], immediately below.  And if the above isn't flexible and you need complete control over all representations see the section on xref:_extending_the_restful_viewer[Extending the Restful viewer] in the <<Extending>> chapter.
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/7db616ea/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration_properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration_properties.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration_properties.adoc
deleted file mode 100644
index 16e8b1c..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration_properties.adoc
+++ /dev/null
@@ -1,182 +0,0 @@
-[[_ug_restfulobjects-viewer_configuration_properties]]
-= Configuration Properties
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-IMPORTANT: WIP...
-
-The Restful Objects viewer provides a number of configuration option that extend/simplify/alter the representations generated from the Restful Objects specification.
-
-These configuration properties are typically stored in `WEB-INF/viewer_restfulobjects.properties`.  However, you can place all configuration properties into `WEB-INF/isis.properties` if you wish (the configuration properties from all config files are merged together).
-
-[WARNING]
-====
-These configuration settings should be considered beta, and may change in the future in response to emerging requirements.
-
-Also, be aware enabling these settings makes the representations with respect to the http://restfulobjects.org[Restful Object spec].  (Based on experience in Isis, in the future the spec may be updated to allow such extensions).
-====
-
-
-.RestfulObjects Viewer Configuration Properties
-[cols="2a,1,3", options="header"]
-|===
-|Property
-|Value +
-(_default value_)
-|Description
-
-|`isis.viewer.restfulobjects.` +
-`honorUiHints`
-| `true`,`false` (`_false_`)
-| See xref:_honor_ui_hints[discussion], below.
-
-|`isis.viewer.restfulobjects.` +
-`suppressDescribedByLinks`
-| `true`,`false` (`_false_`)
-.6+| See xref:_suppressing_elements_of_the_representation[discussion], below.
-
-|`isis.viewer.restfulobjects.` +
-`suppressUpdateLink`
-| `true`,`false` (`_false_`)
-
-|`isis.viewer.restfulobjects.` +
-`suppressMemberId`
-| `true`,`false` (`_false_`)
-
-|`isis.viewer.restfulobjects.` +
-`suppressMemberLinks`
-| `true`,`false` (`_false_`)
-
-|`isis.viewer.restfulobjects.` +
-`suppressMemberExtensions`
-| `true`,`false` (`_false_`)
-
-|`isis.viewer.restfulobjects.` +
-`suppressMemberDisabledReason`
-| `true`,`false` (`_false_`)
-
-|`isis.viewer.restfulobjects.` +
-`objectPropertyValuesOnly`
-| `true`,`false` (`_false_`)
-| See xref:_simplified_object_representation[discussion], below.
-
-|===
-
-
-
-== Honor UI hints
-
-By default the representations generated by Restful Objects ignore any Isis metamodel hints referring to the UI.
-In particular, if a collection is annotated then `Render(EAGERLY)` then the contents of the collection are _not_
-eagerly embedded in the object representation.
-
-However, this behaviour can be overridden globally using following property (typically added to `WEB-INF/viewer_restfulobjects.properties`):
-
-[source,ini]
-----
-isis.viewer.restfulobjects.honorUiHints=true
-----
-
-[NOTE]
-====
-In the future we might extend this per-request.  Raise/vote on a JIRA ticket if you require this feature.
-====
-
-
-
-== Suppressing elements of the representation
-
-The representations specified by the http://restfulobjects.org[Restful Object spec] are very rich in hypermedia controls and metadata, intended to support a wide variety of possible REST clients. However, if an application is providing its REST API only for a small well-defined set of REST clients, then it is possible to suppress (remove) various elements of these representations.
-
-This is done by globally using the following properties (typically added to `WEB-INF/viewer_restfulobjects.properties`):
-
-[source,ini]
-----
-isis.viewer.restfulobjects.suppressDescribedByLinks=true      # <1>
-isis.viewer.restfulobjects.suppressUpdateLink=true            # <2>
-isis.viewer.restfulobjects.suppressMemberId=true              # <3>
-isis.viewer.restfulobjects.suppressMemberLinks=true           # <4>
-isis.viewer.restfulobjects.suppressMemberExtensions=true      # <5>
-isis.viewer.restfulobjects.suppressMemberDisabledReason=true  # <6>
-----
-<1> suppresses the "describedby" links (on all representations)
-<2> suppresses the  "update" link (on object representation)
-<3> suppresses the  "id" json-prop for object members (on object representation and member detail representations)
-<4> suppresses the  "links" json-prop for object members (on the object representation and member detail representations)
-<5> suppresses the  "extensions" json-prop for object members (on the object representation and member detail representations)
-<6> suppresses the  "disabledReason" json-prop for object members (on the object representation and member detail representations)
-
-The defaults for all of these is false, meaning that the hypermedia/metadata is NOT suppressed.
-
-[NOTE]
-====
-In the future we might extend this per-request.  Raise/vote on a JIRA ticket if you require this feature.
-====
-
-If an even simpler representations (of objects) are required, see xref:_simplified_object_representation[simplified object representation], immediately below.  And if the above isn't flexible and you need complete control over all representations see the section on xref:_extending_the_restful_viewer[Extending the Restful viewer] in the <<Extending>> chapter.
-
-
-
-== Simplified object representation
-
-The representations specified by the http://restfulobjects.org[Restful Object spec] are very rich in hypermedia
-controls and metadata, intended to support a wide variety of possible REST clients.
-
-As described xref:_suppressing_elements_of_the_representations[above], it is possible to suppress various elements of these representations. Even then, though, the representations may be too complex for some bespoke REST clients that require a very "flat" object representation.
-
-The Restful Objects viewer therefore supports generating a much simpler representation of objects using the following configuration property (typically added to `WEB-INF/viewer_restfulobjects.properties`):
-
-[source,ini]
-----
-isis.viewer.restfulobjects.objectPropertyValuesOnly=true
-----
-
-This generates a representation such as:
-
-[source,javascript]
-----
-{
-    "title" : "Buy milk due by 2014-10-27",
-    "domainType" : "TODO",
-    "instanceId" : "0",
-    "members" : {
-        "description" : "Buy milk",
-        "category" : "Domestic",
-        "subcategory" : "Shopping",
-        "complete" : false,
-        "versionSequence" : 1,
-        "relativePriority" : 2,
-        "dueBy" : "2014-10-27",
-        "cost" : "0.75",
-        "notes" : null,
-        "attachment" : null,
-        "doc" : null
-    },
-    "links" : [
-        {
-            "rel" : "self",
-            "href" : "http://localhost:8080/restful/objects/TODO/0",
-            "method" : "GET",
-            "type" : "application/json;profile=\"urn:org.restfulobjects:repr-types/object\"",
-            "title" : "Buy milk due by 2014-10-27"
-        },
-        {
-            "rel" : "describedby",
-            "href" : "http://localhost:8080/restful/domain-types/TODO",
-            "method" : "GET",
-            "type" : "application/json;profile=\"urn:org.restfulobjects:repr-types/domain-type\""
-        }
-    ],
-    "extensions" : {
-        "oid" : "TODO:0"
-    },
-}
-----
-
-[NOTE]
-====
-In the future we might extend this per-request.  Raise/vote on a JIRA ticket if you require this feature.
-====
-
-If the above isn't flexible and you need complete control over all representations see the section on xref:_extending_the_restful_viewer[Extending the Restful viewer].

http://git-wip-us.apache.org/repos/asf/isis/blob/7db616ea/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_disabling-persistence-by-reachability.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_disabling-persistence-by-reachability.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_disabling-persistence-by-reachability.adoc
index 990ff0f..8f21be5 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_disabling-persistence-by-reachability.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_disabling-persistence-by-reachability.adoc
@@ -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:__a_id_getting_started_a_simpleapp_archetype[SimpleApp archetype]
+This change has been made to the xref:_ug_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/7db616ea/adocs/documentation/src/main/asciidoc/user-guide/_ug_security.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security.adoc
index e0db433..db77766 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security.adoc
@@ -15,7 +15,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:__a_id_getting_started_a_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:_ug_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.  Isis in turn extends this with its `IsisLdapRealm`, which provides more flexibility for both group/role and role/permissions management.