You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by mg...@apache.org on 2015/12/13 10:37:57 UTC
[18/50] [abbrv] isis git commit: ISIS-1243: renamed ug.adoc to
ugfun.adoc. Added standard section to each of the guides so can navigate
between each easily.
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugtst_fixture-scripts_api-and-usage.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugtst_fixture-scripts_api-and-usage.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugtst_fixture-scripts_api-and-usage.adoc
index ad2a50d..344f32a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugtst_fixture-scripts_api-and-usage.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugtst_fixture-scripts_api-and-usage.adoc
@@ -23,7 +23,7 @@ As of 1.9.0 there is an alternative design. Instead of subclassing `FixtureScri
The actual implementation of the `FixtureScripts` service is then provided by the framework itself, namely the xref:rgsvc.adoc#_rgsvc-api_FixtureScriptsDefault[`FixtureScriptsDefault`] domain service, annotated to be rendered on the secondary "Prototyping" menu. This uses the `FixtureScriptsSpecificationProvider` to adjust itself accordinly.
-For example, here's the `FixtureScriptsSpecificationProvider` service that's generated by the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype]:
+For example, here's the `FixtureScriptsSpecificationProvider` service that's generated by the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]:
[source,java]
----
@@ -113,7 +113,7 @@ If you had defined many fixture scripts then a drop-down might become unwieldy,
----
-You are free, of course, to add additional "convenience" actions into it if you wish for the most commonly used/demo'd setups ; you'll find that the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype] adds this additional action:
+You are free, of course, to add additional "convenience" actions into it if you wish for the most commonly used/demo'd setups ; you'll find that the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] adds this additional action:
[source,java]
----
@@ -139,7 +139,7 @@ Let's now look at the `FixtureScript` class, where there's a bit more going on.
A fixture script is ultimately just a block of code that can be executed, so it's up to you how you implement it to set up the system. However, we strongly recommend that you use it to invoke actions on business objects, in essence to replay what a real-life user would have done. That way, the fixture script will remain valid even if the underlying implementation of the system changes in the future.
-Here's the `RecreateSimpleObjects` fixture script from the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype]:
+Here's the `RecreateSimpleObjects` fixture script from the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]:
[source,java]
----
@@ -251,7 +251,7 @@ public class SimpleObjectCreate extends FixtureScript { // <1>
Fixture scripts can be called from integration tests just the same way that fixture scripts can call one another.
-For example, here's an integration test from the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype]:
+For example, here's an integration test from the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]:
[source,java]
----
@@ -296,7 +296,7 @@ public class SimpleObjectIntegTest extends SimpleAppIntegTest {
There are lots of ways to organize fixture scripts, but we've used them as either:
-* a fairly flat style, eg as in the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype], also as in the http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp];
+* a fairly flat style, eg as in the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype], also as in the http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp];
* in a "composite pattern" style, eg as in the https://github.com/estatio/estatio/blob/ea20a6ce257acede50de6ce4fd2ff29713fcd689/estatioapp/fixture/src/main/java/org/estatio/fixture/invoice/InvoiceForLeaseItemTypeOfDiscountOneQuarterForOxfMiracle005.java#L66)[Estatio open source app].
@@ -318,7 +318,7 @@ image::{_imagesdir}testing/fixture-scripts/composite.png[width="550px",link="{_i
Back in the earlier section we noted the `MultipleExecutionStrategy` setting. We can now explain the meaning of this: the enum value of `EXECUTE` is designed for the flat style (where every fixture script will be called), whereas the enum value of `IGNORE` is designed for the composite style, and ensures that any fixture scripts visited more than once (eg TearDown) are only every executed the first time.
-As already noted , the app generated by the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype] uses the flat structure, and we feel that it's a better at separating out the "how" (how we set up some graph of domain objects into a known state, eg a customer with shipped placed orders and a newly placed order) from the "what" (what data should we actually use for the customer's name, say).
+As already noted , the app generated by the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] uses the flat structure, and we feel that it's a better at separating out the "how" (how we set up some graph of domain objects into a known state, eg a customer with shipped placed orders and a newly placed order) from the "what" (what data should we actually use for the customer's name, say).
The composite style tends to combine these, which one could argue does not separate responsibilities well enough. On the other hand, one could also make an argument that the composite style is a good way to implement precanned personas, eg "Joe", the customer who has a newly placed order, from "Mary" customer who has none.
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugtst_integ-test-support_bootstrapping.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugtst_integ-test-support_bootstrapping.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugtst_integ-test-support_bootstrapping.adoc
index e7b8399..ffa31ef 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugtst_integ-test-support_bootstrapping.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugtst_integ-test-support_bootstrapping.adoc
@@ -11,7 +11,7 @@ Nevertheless, we do need to bootstrap the runtime for the very first test.
As of 1.9.0 the bootstrapping of integration tests and webapps has been simplified through the xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`] class. Since this isn't mandatory, for now we present both techniques.
-The example code in this section is taken from the app generated by the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype].
+The example code in this section is taken from the app generated by the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugtst_integ-test-support_maven-configuration.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugtst_integ-test-support_maven-configuration.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugtst_integ-test-support_maven-configuration.adoc
index 851da7a..587fe92 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugtst_integ-test-support_maven-configuration.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugtst_integ-test-support_maven-configuration.adoc
@@ -5,7 +5,7 @@
:_imagesdir: images/
-Apache Isis' integration test support is automatically configured if you use the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype]. To set it up manually, update the `pom.xml` of your domain object model module:
+Apache Isis' integration test support is automatically configured if you use the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]. To set it up manually, update the `pom.xml` of your domain object model module:
[source,xml]
----
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugtst_unit-test-support_contract-tests.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugtst_unit-test-support_contract-tests.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugtst_unit-test-support_contract-tests.adoc
index 24f7e1e..6171c86 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugtst_unit-test-support_contract-tests.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugtst_unit-test-support_contract-tests.adoc
@@ -64,11 +64,11 @@ public class SortedSetsContractTestAll extends SortedSetsContractTestAbstract {
== Bidirectional
-This contract test automatically checks that bidirectional 1:m or 1:1 associations are being maintained correctly (assuming that they follow the xref:ug.adoc#_ug_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships[mutual registration pattern]
+This contract test automatically checks that bidirectional 1:m or 1:1 associations are being maintained correctly (assuming that they follow the xref:ug.adoc#_ugfun_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships[mutual registration pattern]
[TIP]
====
-(If using the JDO objectstore, then) there is generally no need to programmatically maintain 1:m relationships (indeed it may introduce subtle errors). For more details, see xref:ug.adoc#_ug_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships[here]. Also check out the xref:cg.adoc#_cg_ide-templates[IDE templates] for further guidance.
+(If using the JDO objectstore, then) there is generally no need to programmatically maintain 1:m relationships (indeed it may introduce subtle errors). For more details, see xref:ug.adoc#_ugfun_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships[here]. Also check out the xref:cg.adoc#_cg_ide-templates[IDE templates] for further guidance.
====
For example, suppose that `ParentDomainObject` and `ChildDomainObject` have a 1:m relationship (`ParentDomainObject#children` / `ChildDomainObject#parent`), and also `PeerDomainObject` has a 1:1 relationship with itself (`PeerDomainObject#next` / `PeerDomainObject#previous`).
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugtst_unit-test-support_maven-configuration.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugtst_unit-test-support_maven-configuration.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugtst_unit-test-support_maven-configuration.adoc
index 92f7ffc..9fa4881 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugtst_unit-test-support_maven-configuration.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugtst_unit-test-support_maven-configuration.adoc
@@ -5,7 +5,7 @@
:_imagesdir: images/
-Apache Isis' unit test support is automatically configured if you use the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype]. To set it up manually, update the `pom.xml` of your domain object model module:
+Apache Isis' unit test support is automatically configured if you use the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]. To set it up manually, update the `pom.xml` of your domain object model module:
[source,xml]
----
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugvw_customisation_about-page.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugvw_customisation_about-page.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugvw_customisation_about-page.adoc
index 6ee6f68..8a6426f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugvw_customisation_about-page.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugvw_customisation_about-page.adoc
@@ -31,7 +31,7 @@ If none of these are found, then no version is displayed.
[TIP]
====
-This configuration is included within the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype].
+This configuration is included within the xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
====
=== Adding attributes to the WAR's manifest
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugvw_customisation_tweaking-css-classes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugvw_customisation_tweaking-css-classes.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugvw_customisation_tweaking-css-classes.adoc
index 01eb3d2..5e1d869 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugvw_customisation_tweaking-css-classes.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugvw_customisation_tweaking-css-classes.adoc
@@ -92,7 +92,7 @@ div.x-myapp-highlight span.scalarName {
}
----
-Note also that instead of using `@PropertyLayout(cssClass=...)` annotation, you can also specify the CSS style using a xref:ug.adoc#_ug_object-layout_dynamic[dynamic layout] JSON file:
+Note also that instead of using `@PropertyLayout(cssClass=...)` annotation, you can also specify the CSS style using a xref:ug.adoc#_ugfun_object-layout_dynamic[dynamic layout] JSON file:
[source,javascript]
----
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/_ugvw_layout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugvw_layout.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugvw_layout.adoc
index 75b5e5e..322e045 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugvw_layout.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugvw_layout.adoc
@@ -6,7 +6,7 @@
-The wicket viewer has full support for the various methods of specifying the xref:ug.adoc#_ug_object-layout[layout of objects], either statically or dynamically.
+The wicket viewer has full support for the various methods of specifying the xref:ug.adoc#_ugfun_object-layout[layout of objects], either statically or dynamically.
Dynamic reloading is automatically supported when running in xref:rgcfg.adoc#_rgcfg_deployment-types[prototype (development) mode], the Wicket viewer automatically rebuilds the metamodel for each class as it is rendered. Conversely, do note that the Wicket viewer will *not* pick up new metadata if running in production/server mode.
@@ -46,7 +46,7 @@ And finally, from the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Is
image::{_imagesdir}wicket-viewer/layouts/todoapp-ToDoItem.png[width="800px",link="{_imagesdir}wicket-viewer/layouts/todoapp-ToDoItem.png"]
-To learn more about how to configure these types of layout, see the xref:ug.adoc#_ug_object-layout[object layout] chapter.
+To learn more about how to configure these types of layout, see the xref:ug.adoc#_ugfun_object-layout[object layout] chapter.
@@ -92,6 +92,6 @@ Therefore, make sure the following is added to the dom project's `pom.xml`:
</resources>
----
-If using an Apache Isis xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype], then the POM is already correctly configured.
+If using an Apache Isis xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype], then the POM is already correctly configured.
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/cg.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/cg.adoc b/adocs/documentation/src/main/asciidoc/guides/cg.adoc
index 233d347..9da1818 100644
--- a/adocs/documentation/src/main/asciidoc/guides/cg.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/cg.adoc
@@ -11,13 +11,39 @@
This contributors' guide has three related audiences:
-* programmers who want to just use Apache Isis to build applications, and want help setting up their development environment or to build their code from the command line (eg to execute within a continuous integration server such as Jenkins)
+* programmers who want to just use Apache Isis to build applications, and want help setting up their development
+environment or to build their code from the command line (eg to execute within a continuous integration server such
+as Jenkins)
* programmers who want to contribute back patches (bug fixes, new features) either to the codebase or the framework's documentation
* committers of Apache Isis itself who want guidance on release process, publishing documents and other related procedures.
-This contributors' guide is _not_ intended as a reference manual; for that see the *xref:rg.adoc#_rg[Reference Guide]*. This guide also doesn't describe how to actually build an Apache Isis application; for that see the *xref:ug.adoc#_ug[Users' Guide]*.
+
+
+=== Other Guides
+
+Apache Isis documentation is broken out into a number of user and reference guides.
+
+The user guides available are:
+
+* xref:ugfun.adoc#[Fundamentals]
+* xref:ugvw.adoc#[Wicket viewer]
+* xref:ugvro.adoc#[Restful Objects viewer]
+* xref:ugsec.adoc#[Security]
+* xref:ugtst.adoc#[Testing]
+* xref:ugbtb.adoc#[Beyond the Basics]
+
+The reference guides are:
+
+* xref:rgant.adoc#[Annotations]
+* xref:rgsvc.adoc#[Domain Services]
+* xref:rgcfg.adoc#[Configuration Properties]
+* xref:rg.adoc#[Classes, Methods and Schema]
+
+In addition, there is (this) xref:cg.adoc#_cg[Contributors' Guide] describing development practices for contributors and committers alike.
+
+
include::_cg_ide.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/rg.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rg.adoc b/adocs/documentation/src/main/asciidoc/guides/rg.adoc
new file mode 100644
index 0000000..4711809
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rg.adoc
@@ -0,0 +1,27 @@
+[[rg]]
+= Reference Guides
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the 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/
+:numbered:
+
+
+Apache Isis documentation is broken out into a number of user and reference guides.
+
+The user guides available are:
+
+* xref:ugfun.adoc#[Fundamentals]
+* xref:ugvw.adoc#[Wicket viewer]
+* xref:ugvro.adoc#[Restful Objects viewer]
+* xref:ugsec.adoc#[Security]
+* xref:ugtst.adoc#[Testing]
+* xref:ugbtb.adoc#[Beyond the Basics] (this guide)
+
+The reference guides are:
+
+* xref:rgant.adoc#[Annotations]
+* xref:rgsvc.adoc#[Domain Services]
+* xref:rgcfg.adoc#[Configuration Properties]
+* xref:rg.adoc#[Classes, Methods and Schema]
+
+In addition, there is a xref:cg.adoc#_cg[Contributors' Guide] describing development practices for contributors and committers alike.
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/rgant.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant.adoc
index de65d2e..491e973 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant.adoc
@@ -8,9 +8,36 @@
[[_rgant]]
== Annotations
-Apache Isis uses annotations to provide additional metadata about the domain objects.
+This guide describes the various annotations used by Apache Isis to provide additional metadata about the domain objects.
+Most of these are defined by Isis itself, but some are from other libraries. It also identifies a number of
+annotations that are now deprecated, and indicates their replacement.
-To give just a few examples:
+=== Other Guides
+
+Apache Isis documentation is broken out into a number of user and reference guides.
+
+The user guides available are:
+
+* xref:ugfun.adoc#[Fundamentals]
+* xref:ugvw.adoc#[Wicket viewer]
+* xref:ugvro.adoc#[Restful Objects viewer]
+* xref:ugsec.adoc#[Security]
+* xref:ugtst.adoc#[Testing]
+* xref:ugbtb.adoc#[Beyond the Basics]
+
+The reference guides are:
+
+* xref:rgant.adoc#[Annotations]
+* xref:rgsvc.adoc#[Domain Services]
+* xref:rgcfg.adoc#[Configuration Properties]
+* xref:rg.adoc#[Classes, Methods and Schema]
+
+In addition, there is a xref:cg.adoc#_cg[Contributors' Guide] describing development practices for contributors and committers alike.
+
+
+=== Examples
+
+To give just a few examples of annotations supported by Apache Isis:
* if a property is read-only, then this can be annotated with `@Property(editing=EditingDISABLED)`.
* if a class has a small fixed set of instances (eg a picklist), then it can be annotated using `@DomainObject(bounded=true)`
@@ -24,11 +51,7 @@ Some annotations act as UI hints, for example:
* if an action has a tooltip, it can be annotated using `@ActionLayout(describedAs=...)`
* if a domain object is bookmarkable, it can be annotated using `@DomainObjectLayout(bookmarking=BookmarkPolicy.AS_ROOT`).
-This guide documents all the annotations currently supported by Apache Isis. It also identifies a number of annotations that are now deprecated, and indicates their replacement.
-
-Other guides are:
-* xref:rg.adoc#[Reference Guide]
include::_rgant_aaa.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/rgcfg.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcfg.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcfg.adoc
index a1d2d07..d064cce 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcfg.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcfg.adoc
@@ -11,15 +11,41 @@
Apache Isis' own configuration properties are simple key-value pairs, typically held in the `WEBINF/isis.properties`
file and other related files. This guide describes how to configure an Apache Isis application.
+=== Other Guides
+
+Apache Isis documentation is broken out into a number of user and reference guides.
+
+The user guides available are:
+
+* xref:ugfun.adoc#[Fundamentals]
+* xref:ugvw.adoc#[Wicket viewer]
+* xref:ugvro.adoc#[Restful Objects viewer]
+* xref:ugsec.adoc#[Security]
+* xref:ugtst.adoc#[Testing]
+* xref:ugbtb.adoc#[Beyond the Basics]
+
+The reference guides are:
+
+* xref:rgant.adoc#[Annotations]
+* xref:rgsvc.adoc#[Domain Services]
+* xref:rgcfg.adoc#[Configuration Properties]
+* xref:rg.adoc#[Classes, Methods and Schema]
+
+In addition, there is a xref:cg.adoc#_cg[Contributors' Guide] describing development practices for contributors and committers alike.
+
[NOTE]
====
-Configuration properties for the viewers can be found in the xref:ugvw.adoc#[Wicket Viewer] chapter and the xref:ugvro.adoc#[RestfulObjects viewer] chapter. Likewise[details of configuring security (Apache Shiro) can be found in the xref:ugsec.adoc#[Security] chapter.
+Configuration properties for the viewers can be found in the xref:ugvw.adoc#[Wicket Viewer] guide and the xref:ugvro.adoc#[RestfulObjects viewer] guide. Likewise[details of configuring security (Apache Shiro) can be found in the xref:ugsec.adoc#[Security] guide.
-Also, note that by default the configuration values are part of the built WAR file. Details on how to override these configuration properties externally for different environments can be found in the xref:ugbtb.adoc#_ugbtb_deployment[Deployment] chapter.
+Also, note that by default the configuration values are part of the built WAR file. Details on how to override these
+configuration properties externally for different environments can be found in the
+xref:ugbtb.adoc#_ugbtb_deployment[Beyond the Basics] guide, (deployment chapter).
====
+
+
include::_rgcfg_deployment-types.adoc[leveloffset=+1]
include::_rgcfg_configuration-files.adoc[leveloffset=+1]
include::_rgcfg_specifying-components.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/rgcms.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms.adoc
index 0951d3b..b6dcc5e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms.adoc
@@ -16,8 +16,27 @@ supporting xref:rgcms.adoc#_rgcms_classes[classes].
It also describes the xref:rgcms.adoc#_rgcms_schema[XSD schema] defined by Apache Isis. One use case is for the
JAXB serialization of view models (`1.11.0-SNAPSHOT`).
+=== Other Guides
-This reference guide does _not_ describe how to actually build an Apache Isis application; for that see the *xref:ug.adoc#_ug[Users' Guide]*. The reference guide also doesn't explain how to setup your development environment; for that see the *xref:cg.adoc#_cg[Contributors' Guide]*.
+Apache Isis documentation is broken out into a number of user and reference guides.
+
+The user guides available are:
+
+* xref:ugfun.adoc#[Fundamentals]
+* xref:ugvw.adoc#[Wicket viewer]
+* xref:ugvro.adoc#[Restful Objects viewer]
+* xref:ugsec.adoc#[Security]
+* xref:ugtst.adoc#[Testing]
+* xref:ugbtb.adoc#[Beyond the Basics]
+
+The reference guides are:
+
+* xref:rgant.adoc#[Annotations]
+* xref:rgsvc.adoc#[Domain Services]
+* xref:rgcfg.adoc#[Configuration Properties]
+* xref:rg.adoc#[Classes, Methods and Schema] (this guide)
+
+In addition, there is a xref:cg.adoc#_cg[Contributors' Guide] describing development practices for contributors and committers alike.
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/rgsvc.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc.adoc
index b1a15fd..a141126 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc.adoc
@@ -12,10 +12,27 @@ This guide documents Apache Isis' domain services, both those that act as an xre
(implemented by the framework for your domain objects to call), and those domain services that act as an
xref:rgsvc.adoc#_rgsvc-spi[SPI] (implemented by your domain application and which are called by the framework).
-Other guides are:
+=== Other Guides
+
+Apache Isis documentation is broken out into a number of user and reference guides.
+
+The user guides available are:
+
+* xref:ugfun.adoc#[Fundamentals]
+* xref:ugvw.adoc#[Wicket viewer]
+* xref:ugvro.adoc#[Restful Objects viewer]
+* xref:ugsec.adoc#[Security]
+* xref:ugtst.adoc#[Testing]
+* xref:ugbtb.adoc#[Beyond the Basics]
+
+The reference guides are:
-* xref:rg.adoc#[Reference Guide]
* xref:rgant.adoc#[Annotations]
+* xref:rgsvc.adoc#[Domain Services] (this guide)
+* xref:rgcfg.adoc#[Configuration Properties]
+* xref:rg.adoc#[Classes, Methods and Schema]
+
+In addition, there is a xref:cg.adoc#_cg[Contributors' Guide] describing development practices for contributors and committers alike.
include::_rgsvc-api.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/simpleapp-archetype.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/simpleapp-archetype.adoc b/adocs/documentation/src/main/asciidoc/guides/simpleapp-archetype.adoc
index c600809..5aa2ba1 100644
--- a/adocs/documentation/src/main/asciidoc/guides/simpleapp-archetype.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/simpleapp-archetype.adoc
@@ -95,7 +95,7 @@ where `myapp` is the `artifactId` entered above.
== Running the App
-The `simpleapp` archetype generates a single WAR file, configured to run both the link:./guides/ug.html#_ug_wicket-viewer[Wicket viewer] and the link:./guides/ug.html#_ugvro[Restful Objects viewer]. The archetype also configures the JDO/DataNucleus objectstore to use an in-memory HSQLDB connection.
+The `simpleapp` archetype generates a single WAR file, configured to run both the link:./guides/ugvw.html#[Wicket viewer] and the link:./guides/ugvro.html#[Restful Objects viewer]. The archetype also configures the JDO/DataNucleus objectstore to use an in-memory HSQLDB connection.
Once you've built the app, you can run the WAR in a variety of ways.
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/ug.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ug.adoc b/adocs/documentation/src/main/asciidoc/guides/ug.adoc
index de52f80..c34ef34 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ug.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ug.adoc
@@ -1,46 +1,27 @@
[[ug]]
-= Fundamentals
+= User Guides
:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the 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/
:numbered:
-[[_ug]]
-== Fundamentals
+Apache Isis documentation is broken out into a number of user and reference guides.
-This guide introduces the xref:ug.adoc#_ug_core-concepts[core concepts] and ideas behind Apache Isis,
-and tells you how to xref:ug.adoc#_ug_getting-started[get started] with a Maven archetype.
-
-It also describes a number of xref:ug.adoc#_ug_how-tos[how-to]s, describes how to influence the
-xref:ug.adoc#_ug_object-layout[UI layout] of your domain objects (this is ultimately just a type of metadata), and it
- catalogues various xref:ug.adoc#_ug_faqs.adoc[FAQ]s.
-
-Other user guides are:
+The user guides available are:
+* xref:ugfun.adoc#[Fundamentals]
* xref:ugvw.adoc#[Wicket viewer]
* xref:ugvro.adoc#[Restful Objects viewer]
* xref:ugsec.adoc#[Security]
* xref:ugtst.adoc#[Testing]
-* xref:ugbtb.adoc#[Beyond the Basics]
+* xref:ugbtb.adoc#[Beyond the Basics] (this guide)
-Other reference guides are:
+The reference guides are:
* xref:rgant.adoc#[Annotations]
* xref:rgsvc.adoc#[Domain Services]
* xref:rgcfg.adoc#[Configuration Properties]
* xref:rg.adoc#[Classes, Methods and Schema]
-This users' guide is _not_ intended as a reference manual; for that see the *xref:rg.adoc#_rg[Reference Guide]*. This
-guide also doesn't explain how to setup your development environment; for that see the *xref:cg.adoc#_cg[Contributors' Guide]*.
-
-
-
-include::_ug_core-concepts.adoc[leveloffset=+1]
-include::_ug_getting-started.adoc[leveloffset=+1]
-
-include::_ug_how-tos.adoc[leveloffset=+1]
-include::_ug_object-layout.adoc[leveloffset=+1]
-
-include::_ug_faqs.adoc[leveloffset=+1]
-
+In addition, there is a xref:cg.adoc#_cg[Contributors' Guide] describing development practices for contributors and committers alike.
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/ugbtb.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb.adoc
index 7201821..7001a58 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb.adoc
@@ -14,16 +14,27 @@ applications.
Later chapters discuss how to xref:ugbtb.adoc#_ugbtb_deployment[deploy] your app, and discuss other ways in which you can xref:ugbtb.adoc#[extend] or adapt the framework itself to your particular needs.
-Other guides are:
+=== Other Guides
-* xref:ug.adoc#[Fundamentals]
+Apache Isis documentation is broken out into a number of user and reference guides.
+
+The user guides available are:
+
+* xref:ugfun.adoc#[Fundamentals]
* xref:ugvw.adoc#[Wicket viewer]
* xref:ugvro.adoc#[Restful Objects viewer]
-* xref:ugvro.adoc#[Security]
+* xref:ugsec.adoc#[Security]
* xref:ugtst.adoc#[Testing]
+* xref:ugbtb.adoc#[Beyond the Basics] (this guide)
+
+The reference guides are:
+* xref:rgant.adoc#[Annotations]
+* xref:rgsvc.adoc#[Domain Services]
+* xref:rgcfg.adoc#[Configuration Properties]
+* xref:rg.adoc#[Classes, Methods and Schema]
-This users' guide is _not_ intended as a reference manual; for that see the *xref:rg.adoc#_rg[Reference Guide]*. This guide also doesn't explain how to setup your development environment; for that see the *xref:cg.adoc#_cg[Contributors' Guide]*.
+In addition, there is a xref:cg.adoc#_cg[Contributors' Guide] describing development practices for contributors and committers alike.
include::_ugbtb_more-advanced.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/ugfun.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun.adoc
new file mode 100644
index 0000000..00abbf2
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun.adoc
@@ -0,0 +1,50 @@
+[[ugfun]]
+= Fundamentals
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the 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/
+:numbered:
+
+
+[[_ugfun]]
+== Fundamentals
+
+This guide introduces the xref:ug.adoc#_ugfun_core-concepts[core concepts] and ideas behind Apache Isis,
+and tells you how to xref:ug.adoc#_ugfun_getting-started[get started] with a Maven archetype.
+
+It also describes a number of xref:ug.adoc#_ugfun_how-tos[how-to]s, describes how to influence the
+xref:ug.adoc#_ugfun_object-layout[UI layout] of your domain objects (this is ultimately just a type of metadata), and it
+ catalogues various xref:ug.adoc#_ugfun_faqs.adoc[FAQ]s.
+
+=== Other Guides
+
+Apache Isis documentation is broken out into a number of user and reference guides.
+
+The user guides available are:
+
+* xref:ugfun.adoc#[Fundamentals] (this guide)
+* xref:ugvw.adoc#[Wicket viewer]
+* xref:ugvro.adoc#[Restful Objects viewer]
+* xref:ugsec.adoc#[Security]
+* xref:ugtst.adoc#[Testing]
+* xref:ugbtb.adoc#[Beyond the Basics]
+
+The reference guides are:
+
+* xref:rgant.adoc#[Annotations]
+* xref:rgsvc.adoc#[Domain Services]
+* xref:rgcfg.adoc#[Configuration Properties]
+* xref:rg.adoc#[Classes, Methods and Schema]
+
+In addition, there is a xref:cg.adoc#_cg[Contributors' Guide] describing development practices for contributors and committers alike.
+
+
+
+include::_ugfun_core-concepts.adoc[leveloffset=+1]
+include::_ugfun_getting-started.adoc[leveloffset=+1]
+
+include::_ugfun_how-tos.adoc[leveloffset=+1]
+include::_ugfun_object-layout.adoc[leveloffset=+1]
+
+include::_ugfun_faqs.adoc[leveloffset=+1]
+
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/ugsec.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugsec.adoc b/adocs/documentation/src/main/asciidoc/guides/ugsec.adoc
index e27a67a..34f9de3 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugsec.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugsec.adoc
@@ -10,14 +10,29 @@
This guide describes the authentication and authorization features available to secure your Apache Isis application.
-Other guides are:
-* xref:ug.adoc#[Fundamentals]
+=== Other Guides
+
+Apache Isis documentation is broken out into a number of user and reference guides.
+
+The user guides available are:
+
+* xref:ugfun.adoc#[Fundamentals]
* xref:ugvw.adoc#[Wicket viewer]
* xref:ugvro.adoc#[Restful Objects viewer]
+* xref:ugsec.adoc#[Security] (this guide)
* xref:ugtst.adoc#[Testing]
* xref:ugbtb.adoc#[Beyond the Basics]
+The reference guides are:
+
+* xref:rgant.adoc#[Annotations]
+* xref:rgsvc.adoc#[Domain Services]
+* xref:rgcfg.adoc#[Configuration Properties]
+* xref:rg.adoc#[Classes, Methods and Schema]
+
+In addition, there is a xref:cg.adoc#_cg[Contributors' Guide] describing development practices for contributors and committers alike.
+
=== Terminology
@@ -31,7 +46,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:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype] is configured to use this realm.
+Shiro ships with a simple text-based realm -- the `IniRealm` -- which reads users (and password), user roles and role permissions from the `WEB-INF/shiro.ini` file. The xref:ug.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] is configured to use this realm.
Shiro also ships with an implementation of an LDAP-based realm; LDAP is often used to manage user/passwords and corresponding user groups. Apache Isis in turn extends this with its `IsisLdapRealm`, which provides more flexibility for both group/role and role/permissions management.
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/ugtst.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugtst.adoc b/adocs/documentation/src/main/asciidoc/guides/ugtst.adoc
index 20f81fa..1997486 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugtst.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugtst.adoc
@@ -16,14 +16,28 @@ application frameworks.
This guide describes those features available to you for testing your Apache Isis application.
-Other guides are:
+=== Other Guides
-* xref:ug.adoc#[Fundamentals]
+Apache Isis documentation is broken out into a number of user and reference guides.
+
+The user guides available are:
+
+* xref:ugfun.adoc#[Fundamentals]
* xref:ugvw.adoc#[Wicket viewer]
* xref:ugvro.adoc#[Restful Objects viewer]
* xref:ugsec.adoc#[Security]
+* xref:ugtst.adoc#[Testing] (this guide)
* xref:ugbtb.adoc#[Beyond the Basics]
+The reference guides are:
+
+* xref:rgant.adoc#[Annotations]
+* xref:rgsvc.adoc#[Domain Services]
+* xref:rgcfg.adoc#[Configuration Properties]
+* xref:rg.adoc#[Classes, Methods and Schema]
+
+In addition, there is a xref:cg.adoc#_cg[Contributors' Guide] describing development practices for contributors and committers alike.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/ugvro.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvro.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvro.adoc
index 4d6738a..2dbdd6c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvro.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvro.adoc
@@ -14,14 +14,28 @@ which defines a generic way to expose a domain model through a REST (or more pre
This user guide discuss features, configuration and how to extend the Restful Objects viewer.
-Other guides are:
+=== Other Guides
-* xref:ug.adoc#[Fundamentals]
+Apache Isis documentation is broken out into a number of user and reference guides.
+
+The user guides available are:
+
+* xref:ugfun.adoc#[Fundamentals]
* xref:ugvw.adoc#[Wicket viewer]
+* xref:ugvro.adoc#[Restful Objects viewer] (this guide)
* xref:ugsec.adoc#[Security]
* xref:ugtst.adoc#[Testing]
* xref:ugbtb.adoc#[Beyond the Basics]
+The reference guides are:
+
+* xref:rgant.adoc#[Annotations]
+* xref:rgsvc.adoc#[Domain Services]
+* xref:rgcfg.adoc#[Configuration Properties]
+* xref:rg.adoc#[Classes, Methods and Schema]
+
+In addition, there is a xref:cg.adoc#_cg[Contributors' Guide] describing development practices for contributors and committers alike.
+
include::_ugvro_features.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/1ad82470/adocs/documentation/src/main/asciidoc/guides/ugvw.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw.adoc
index 0fdda17..bfe7b43 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw.adoc
@@ -18,14 +18,28 @@ This user guide discuss end-user features, configuration and customization of th
It also discusses how to extend the viewer, and the (non-ASF) link:http://isisaddons.org[Isis Addons] wicket components.
-Other guides are:
+=== Other Guides
-* xref:ug.adoc#[Fundamentals]
+Apache Isis documentation is broken out into a number of user and reference guides.
+
+The user guides available are:
+
+* xref:ugfun.adoc#[Fundamentals]
+* xref:ugvw.adoc#[Wicket viewer] (this guide)
* xref:ugvro.adoc#[Restful Objects viewer]
* xref:ugsec.adoc#[Security]
* xref:ugtst.adoc#[Testing]
* xref:ugbtb.adoc#[Beyond the Basics]
+The reference guides are:
+
+* xref:rgant.adoc#[Annotations]
+* xref:rgsvc.adoc#[Domain Services]
+* xref:rgcfg.adoc#[Configuration Properties]
+* xref:rg.adoc#[Classes, Methods and Schema]
+
+In addition, there is a xref:cg.adoc#_cg[Contributors' Guide] describing development practices for contributors and committers alike.
+