You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2017/03/24 07:39:56 UTC
[1/5] isis git commit: ISIS-1521: fixes corresponding to PRs #72, #73,
#74
Repository: isis
Updated Branches:
refs/heads/master 6c74c9b85 -> 6ed4f3b74
ISIS-1521: fixes corresponding to PRs #72, #73, #74
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/55504fae
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/55504fae
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/55504fae
Branch: refs/heads/master
Commit: 55504faeba187ab23e868862dde2a2b6fea92442
Parents: 6c74c9b
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Wed Mar 22 06:52:36 2017 +0000
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Wed Mar 22 06:52:36 2017 +0000
----------------------------------------------------------------------
.../guides/_ugfun_how-tos_class-structure_collections.adoc | 2 +-
.../guides/_ugfun_how-tos_class-structure_properties.adoc | 8 ++++----
2 files changed, 5 insertions(+), 5 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/55504fae/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_collections.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_collections.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_collections.adoc
index b1b69ec..fe7cfdf 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_collections.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_collections.adoc
@@ -27,7 +27,7 @@ Apache Isis recognises some of these annotations for JDO/DataNucleus and JAXB an
Unlike xref:ugfun.adoc#_ugfun_how-tos_class-structure_properties[properties], the framework (at least, the xref:ugvw.adoc[Wicket viewer]) does not allow collections to be "edited".
Instead, xref:ugfun.adoc#_ugfun_how-tos_class-structure_actions[action]s can be written that will modify the contents of the collection as a side-effect.
-For example, a `placeOrder(...)` action will likely add to an `Order` to the `Customer#orders` collection.
+For example, a `placeOrder(...)` action will likely add an `Order` to the `Customer#orders` collection.
Since writing getter and setter methods adds quite a bit of boilerplate, it's common to use link:https://projectlombok.org/[Project Lombok] to code generate these methods at compile time (using Java's annotation processor) simply by adding the `@lombok.Getter` and `@lombok.Setter` annotations to the field.
http://git-wip-us.apache.org/repos/asf/isis/blob/55504fae/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_properties.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_properties.adoc
index 008c4fa..e0bf17c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_properties.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_properties.adoc
@@ -8,7 +8,7 @@
A property is an instance variable of a domain object, of a scalar type, that holds some state about either a xref:ugfun.adoc#__ugfun_how-tos_class-structure_class-definition_entities[domain entity] or a xref:ugfun.adoc#__ugfun_how-tos_class-structure_class-definition_view-models[view model].
For example, a ``Customer``'s `firstName` would be a property, as would their `accountCreationDate` that they created their account.
-All properties have at least a "getter" method, and most properties have also a "setter" method (meaning that they are immutable).
+All properties have at least a "getter" method, and most properties have also a "setter" method (meaning that they are mutable).
Properties that do _not_ have a setter method are derived properties, and so are not persisted.
Formally speaking, a property is simply a regular JavaBean getter, returning a scalar value recognized by the framework.
@@ -33,7 +33,7 @@ The xref:guides/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp
[[__ugfun_how-tos_class-structure_properties_value-vs-reference-types]]
== Value vs Reference Types
-Properties can be either a value types (strings, int, date and so on) or be a reference to another object (for example, an `Order` referencing the `Customer` that placed it).
+Properties can be either a value type (strings, int, date and so on) or be a reference to another object (for example, an `Order` referencing the `Customer` that placed it).
For example, to map a string value type:
@@ -53,7 +53,7 @@ You could also add the `@Property` annotation if you wished:
private String notes;
----
-Although in this case it is not required in this case (none of its attributes have been set).
+Although in this case it is not required (none of its attributes have been set).
Or to map a reference type:
@@ -367,7 +367,7 @@ whereby a single table corresponds to the superclass, and also holds the propert
* "table per class" (`InheritanceStrategy.NEW_TABLE`) +
+
-whereby is a table for both superclass and subclass, in 1:1 correspondence
+whereby there is a table for both superclass and subclass, in 1:1 correspondence
* "rolldown" (`InheritanceStrategy.SUBCLASS_TABLE`) +
+
[2/5] isis git commit: ISIS-1521: adds asciidoc syntax as an appendix.
Posted by da...@apache.org.
ISIS-1521: adds asciidoc syntax as an appendix.
Fixes some bad links to DN objectstore guide
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/d0edbd42
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/d0edbd42
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/d0edbd42
Branch: refs/heads/master
Commit: d0edbd424f8501fdc6d4f3c14f9616526cb63e71
Parents: 55504fa
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Fri Mar 24 06:58:37 2017 +0000
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Fri Mar 24 06:58:37 2017 +0000
----------------------------------------------------------------------
adocs/documentation/preview-html.sh | 2 +
.../src/main/asciidoc/documentation.adoc | 1 +
.../asciidoc/guides/_dg_asciidoc-syntax.adoc | 985 +++++++++++++++++++
.../asciidoc/guides/_dg_asciidoc-templates.adoc | 223 +++--
...fun_how-tos_class-structure_collections.adoc | 2 +-
.../src/main/asciidoc/guides/cgcom.adoc | 2 +-
.../src/main/asciidoc/guides/dg.adoc | 3 +-
.../src/main/asciidoc/guides/rgant.adoc | 2 +-
.../src/main/asciidoc/guides/rgcfg.adoc | 2 +-
.../src/main/asciidoc/guides/rgcms.adoc | 2 +-
.../src/main/asciidoc/guides/rgfis.adoc | 2 +-
.../src/main/asciidoc/guides/rgmvn.adoc | 2 +-
.../src/main/asciidoc/guides/rgsvc.adoc | 2 +-
.../src/main/asciidoc/guides/ugbtb.adoc | 2 +-
.../src/main/asciidoc/guides/ugfun.adoc | 2 +-
.../src/main/asciidoc/guides/ugodn.adoc | 12 +-
.../src/main/asciidoc/guides/ugsec.adoc | 2 +-
.../src/main/asciidoc/guides/ugtst.adoc | 2 +-
.../src/main/asciidoc/guides/ugvro.adoc | 2 +-
.../src/main/asciidoc/guides/ugvw.adoc | 2 +-
20 files changed, 1135 insertions(+), 119 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/d0edbd42/adocs/documentation/preview-html.sh
----------------------------------------------------------------------
diff --git a/adocs/documentation/preview-html.sh b/adocs/documentation/preview-html.sh
new file mode 100644
index 0000000..c1350df
--- /dev/null
+++ b/adocs/documentation/preview-html.sh
@@ -0,0 +1,2 @@
+#!/usr/bin/env bash
+mvn compile -o && python -m webbrowser -t http://localhost:8000 && pushd target/site && python -m http.server 8000 && popd
http://git-wip-us.apache.org/repos/asf/isis/blob/d0edbd42/adocs/documentation/src/main/asciidoc/documentation.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/documentation.adoc b/adocs/documentation/src/main/asciidoc/documentation.adoc
index c93c7f0..fb9a535 100644
--- a/adocs/documentation/src/main/asciidoc/documentation.adoc
+++ b/adocs/documentation/src/main/asciidoc/documentation.adoc
@@ -83,6 +83,7 @@ pass:[<br/>]
* *link:./guides/dg.html[Developers' Guide^]* image:{_imagesdir}PDF-50.png[width="20px" link="./guides/dg.pdf"]
** Setting up link:./guides/dg.html#_dg_ide_intellij[IntelliJ^] or link:./guides/dg.html#_dg_ide_eclipse[Eclipse^]
** link:./guides/dg.html#_dg_contributing[Contributing patches^] (pull requests)
+** link:./guides/dg.html#_dg_asciidoc-syntax[Asciidoc syntax^]
* link:./guides/cgcom.html[Committers' Guide^] image:{_imagesdir}PDF-50.png[width="20px" link="./guides/cgcom.pdf"]
** link:./guides/cgcom.html#_cgcom_cutting-a-release[Cutting a release^]
http://git-wip-us.apache.org/repos/asf/isis/blob/d0edbd42/adocs/documentation/src/main/asciidoc/guides/_dg_asciidoc-syntax.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_dg_asciidoc-syntax.adoc b/adocs/documentation/src/main/asciidoc/guides/_dg_asciidoc-syntax.adoc
new file mode 100644
index 0000000..e113c5f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_dg_asciidoc-syntax.adoc
@@ -0,0 +1,985 @@
+[[_dg_asciidoc-syntax]]
+= Appendix: Asciidoc Syntax
+:notice: licensed to the apache software foundation (asf) under one or more contributor license agreements. see the notice file distributed with this work for additional information regarding copyright ownership. the asf licenses this file to you under the apache license, version 2.0 (the "license"); you may not use this file except in compliance with the license. you may obtain a copy of the license at. http://www.apache.org/licenses/license-2.0 . unless required by applicable law or agreed to in writing, software distributed under the license is distributed on an "as is" basis, without warranties or conditions of any kind, either express or implied. see the license for the specific language governing permissions and limitations under the license.
+:_basedir: ../
+:_imagesdir: images/
+:toc: right
+
+
+
+This appendix describes the main syntax conventions when writing Asciidoctor/Asciidoc.
+
+For more info, see:
+
+* link:_resources/asciidoc-syntax-quick-reference.pdf[asciidoc-syntax-quick-reference.pdf]
+
+* link:_resources/asciidoc-writers-guide.pdf[asciidoc-writers-guide.pdf]
+
+* link:https://powerman.name/doc/asciidoc[online cheat sheet]
+
+* link:http://asciidoctor.org/docs/user-manual/[asciidoctor online user manual]
+
+* link:http://www.methods.co.nz/asciidoc/userguide.html[asciidoc online user manual]
+
+
+[[__markup-docs_asciidoc_headings]]
+== Headings
+
+The number of preceding `=` signs indicates the heading level.
+
+[cols="3a,2a", options="header"]
+|===
+
+| Syntax
+| Meaning
+
+|....
+= Level 1
+....
+
+|There can only be one level 1 per .adoc (at the very top).
+
+The paragraph immediately following the heading is the "preamble", and is rendered in a larger font.
+It's therefore a good place to summarize the content of the document.
+
+|....
+== Level 2
+....
+
+|Level 2
+
+|....
+=== Level 3
+....
+
+|Level 3
+
+|....
+==== Level 4
+....
+|Level 4
+
+|===
+
+
+[[__markup-docs_asciidoc_paragraphs]]
+== Paragraphs
+
+[cols="3a,2a", options="header"]
+|===
+
+| Syntax
+| Example
+
+|....
+Paragraphs are separated by one or more blank lines.
+
+So, this is a separate paragraph.
+....
+
+|Paragraphs are separated by one or more blank lines.
+
+So, this is a separate paragraph.
+
+
+|....
+All consecutive sentences are rendered in the same paragraph.
+This is another sentence in the para.
+And another one.
+Yet another.
+....
+
+|Sentences without a blank line are in the same paragraph.
+Don't worry about word wrapping, just start the next sentence on the next line.
+
+|===
+
+
+In general, there's no need to indent paragraphs; keep things left-aligned.
+Let the markup specify the logical indentation.
+
+.Start each sentence on a new line
+****
+Don't worry about wrapping sentences at 80 characters, just start each new sentence on a new line.
+Asciidoc will take care of the rendering.
+
+This simple tip has a number of other benefits:
+
+1. when the document is edited (eg correct a typo or insert a missing word), then only a single line in the file is changed. +
++
+This will reduce change of merge conflicts, too.
+
+2. You can easily see if a sentence is too long, and should be split
+
+3. You can easily see if all sentences are the same length: good writing should vary the length of sentences
+
+4. You can easily see if successive sentences start with the same phrase (that might be a good thing, or a bad thing, depending).
+
+****
+
+
+[[__markup-docs_asciidoc_bulleted-lists]]
+== Bulleted lists
+
+[cols="3a,2a", options="header"]
+|===
+
+| Syntax
+| Example
+
+|....
+The blank line after this para is required:
+
+* Bullet 1 +
++
+Indented paragraph (note the '+' to to chain this para with the bullet)
+
+* Bullet 2
+
+** Child bullets +
++
+More indenting
+
+** Another child bullet
+
+* Bullet 3
+....
+
+|The blank line after this para is required:
+
+* Bullet 1 +
++
+Indented paragraph (note the '+' to chain this para with the bullet)
+
+* Bullet 2
+
+** Child bullets +
++
+More indenting
+
+** Another child bullet
+
+* Bullet 3
+
+|===
+
+
+[[__markup-docs_asciidoc_numbered-lists]]
+== Numbered lists
+
+There's no need to keep track of numbers, just use '1' or 'a' etc:
+
+[cols="3a,2a", options="header"]
+|===
+
+| Syntax
+| Example
+
+|....
+The blank line after this para is required:
+
+1. Bullet 1 +
++
+Indented paragraph
+
+2. Bullet 2
+
+a. Child bullets +
++
+More indenting
+
+b. Another child bullet
+
+3. Bullet 3
+....
+
+|The blank line after this para is required:
+
+1. Bullet 1 +
++
+Indented paragraph
+
+2. Bullet 2
+
+a. Child bullets +
++
+More indenting
+
+b. Another child bullet
+
+3. Bullet 3
+
+|===
+
+While it isn't necessary to maintain the ordering manually (could just use '1' for all bullets), this does generate warnings when the document is built.
+
+
+[[__markup-docs_asciidoc_links-and-xrefs]]
+== Links and Cross-references
+
+[cols="3a,2a,3a", options="header"]
+|===
+
+| Syntax
+| Example
+| Purpose
+
+|....
+link:http://ciserver:8080[CI Server]
+....
+|link:http://ciserver:8080[CI Server]
+|Link to an external hyperlink
+
+|....
+link:http://ciserver:8080[CI Server^]
+....
+|link:http://ciserver:8080[CI Server^]
+|Link to an external hyperlink, with `target=blank`
+
+|....
+xref:_markup-docs_background[background]
+....
+|xref:_markup-docs_background[background]
+|Cross-reference to section in same asciidoc document
+
+|....
+xref:../../setting-up/concepts/concepts.adoc#[concepts]
+....
+|xref:../../setting-up/concepts/concepts.adoc#[concepts]
+|Cross-reference to top-level of different asciidoc document
+
+|....
+xref:../../setting-up/concepts/concepts.adoc#_concepts_ci-as-a-service[CI as a service]
+....
+|xref:../../setting-up/concepts/concepts.adoc#_concepts_ci-as-a-service[CI as a service]
+|Cross-reference to section within different asciidoc document
+
+|===
+
+
+
+[[__markup-docs_asciidoc_tables]]
+== Tables
+
+....
+.Some table
+[cols="3a,2a", options="header"]
+|===
+
+| Header col 1
+| Header col 2
+
+| Row 1 col 1
+| Row 1 col 2
+
+| Row 2 col 1
+| Row 2 col 2
+
+|===
+....
+
+renders as:
+
+.Some table
+[cols="3a,2a", options="header"]
+|===
+
+| Header col 1
+| Header col 2
+
+| Row 1 col 1
+| Row 1 col 2
+
+| Row 2 col 1
+| Row 2 col 2
+
+|===
+
+where:
+
+* the `cols` attribute says how many columns there are and their respective widths.
+* the "a" suffix indicates that the contents is parsed as Asciidoc
+
+=== Column Attributes
+
+Other options are (link:http://mrhaki.blogspot.co.uk/2014/11/awesome-asciidoctor-styling-columns-and.html[credit]):
+
+* e: emphasized
+* a: Asciidoc markup
+* m: monospace
+* h: header style, all column values are styled as header
+* s: strong
+* l: literal, text is shown in monospace font and line breaks are kept
+* d: default
+* v: verse, keeps line breaks
+
+For example:
+
+....
+.Table with column style e,a,m
+[cols="e,a,m"]
+|===
+| Emphasized (e) | Asciidoc (a) | Monospaced (m)
+
+| Asciidoctor
+| NOTE: *Awesome* way to write documentation
+| It is just code
+
+|===
+....
+
+renders as
+
+.Table with column style e,a,m
+[cols="e,a,m"]
+|===
+| Emphasized (e) | Asciidoc (a) | Monospaced (m)
+
+| Asciidoctor
+| NOTE: *Awesome* way to write documentation
+| It is just code
+
+|===
+
+and:
+
+....
+.Table with column style h,s,l
+[cols="h,s,l"]
+|===
+| Header (h) | Strong (s) | Literal (l)
+
+| Asciidoctor
+| Awesome way to write documentation
+| It is
+just code
+
+|===
+....
+
+renders as
+
+.Table with column style h,s,l
+[cols="h,s,l"]
+|===
+| Header (h) | Strong (s) | Literal (l)
+
+| Asciidoctor
+| Awesome way to write documentation
+| It is
+just code
+
+|===
+
+and:
+
+....
+.Table with column style d,v
+[cols="d,v"]
+|===
+| Default (d) | Verse (v)
+
+| Asciidoctor
+| Awesome way
+to write
+documentation
+
+|===
+....
+
+renders as
+
+.Table with column style d,v
+[cols="d,v"]
+|===
+| Default (d) | Verse (v)
+
+| Asciidoctor
+| Awesome way
+to write
+documentation
+
+|===
+
+
+=== Column Alignment
+
+This can be combined with alignment markers (link:http://mrhaki.blogspot.co.uk/2014/11/awesome-asciidoctor-table-column-and.html[credit]):
+
+* <: top align values (default)
+* >: bottom align values
+* ^: center values
+
+For example:
+
+....
+[cols="^.>,<.<,>.^", options="header"]
+|===
+
+| Name
+| Description
+| Version
+
+| Asciidoctor
+| Awesome way to write documentation
+| 1.5.0
+|===
+....
+
+renders as:
+
+[cols="^.>,<.<,>.^", options="header"]
+|===
+
+| Name
+| Description
+| Version
+
+| Asciidoctor
+| Awesome way to write documentation
+| 1.5.0
+|===
+
+where:
+
+* the first column is centered and bottom aligned,
+* the second column is left and top aligned and
+* the third column is right aligned and centered vertically.
+
+
+=== Column/Row Spanning
+
+We can also have columns or rows spanning multiple cells (link:http://mrhaki.blogspot.co.uk/2014/12/awesome-asciidoctor-span-cell-over-rows.html[credit]):
+
+For example:
+
+....
+.Cell spans columns
+|===
+| Name | Description
+
+| Asciidoctor
+| Awesome way to write documentation
+
+2+| The statements above say it all
+
+|===
+....
+
+renders as:
+
+
+.Cell spans columns
+|===
+| Name | Description
+
+| Asciidoctor
+| Awesome way to write documentation
+
+2+| The statements above say it all
+
+|===
+
+The `N+` sign notation tells Asciidoctor to span this cell over N columns.
+
+
+while:
+
+....
+.Cell spans rows
+|===
+| Name | Description
+
+.2+| Asciidoctor
+| Awesome way to write documentation
+
+| Works on the JVM
+
+|===
+....
+
+renders as:
+
+
+.Cell spans rows
+|===
+| Name | Description
+
+.2+| Asciidoctor
+| Awesome way to write documentation
+
+| Works on the JVM
+
+|===
+
+The `.N+` notation tells Asciidoctor to span this cell over N rows.
+
+
+and:
+
+....
+.Cell spans both rows and columns
+|===
+
+| Row 1, Col 1 | Row 1, Col 2 | Row 1, Col 3
+
+2.2+| Cell spans 2 cols, 2 rows
+| Row 2, Col 3
+| Row 3, Col 3
+
+|===
+....
+
+renders as:
+
+.Cell spans both rows and columns
+|===
+
+| Row 1, Col 1 | Row 1, Col 2 | Row 1, Col 3
+
+2.2+| Cell spans 2 cols, 2 rows
+| Row 2, Col 3
+| Row 3, Col 3
+
+|===
+
+The `N.M+` notation tells Asciidoctor to span this cell over N columns and M rows.
+
+
+
+[[__markup-docs_asciidoc_admonitions]]
+== Admonitions
+
+Callout or highlight content of particular note.
+
+[cols="3a,2a", options="header"]
+|===
+
+| Syntax
+| Example
+
+|....
+NOTE: the entire note must be a single sentence.
+....
+
+|NOTE: the entire note must be a single sentence.
+
+|....
+[NOTE]
+====
+the note is multiple paragraphs, and can have all the usual styling,
+* eg bullet points:
+* etc etc
+====
+....
+
+|
+[NOTE]
+====
+the note is multiple paragraphs, and can have all the usual styling,
+
+* eg bullet points:
+* etc etc
+====
+
+|....
+[TIP]
+====
+Here's something worth knowing...
+====
+....
+
+|
+[TIP]
+====
+Here's something worth knowing...
+====
+
+
+|....
+[WARNING]
+====
+Be careful...
+====
+....
+
+|
+[WARNING]
+====
+Be careful...
+====
+
+|....
+[IMPORTANT]
+====
+Don't forget...
+====
+....
+
+|
+[IMPORTANT]
+====
+Don't forget...
+====
+
+|===
+
+
+[[__markup-docs_asciidoc_source-code]]
+== Source code
+
+Use `[source]` macro to specify source content:
+
+....
+[source,powershell]
+----
+get-command -module BomiArtifact
+----
+....
+
+will render as:
+
+[source,powershell]
+----
+get-command -module BomiArtifact
+----
+
+Some languages support syntax highlighting.
+For example:
+
+....
+[source,java]
+----
+public class SomeClass extends SomeOtherClass {
+ ...
+}
+----
+....
+
+will render as:
+
+[source,java]
+----
+public class SomeClass extends SomeOtherClass {
+ ...
+}
+----
+
+Callouts can also be added using an appropriate comment syntax.
+For example:
+
+....
+[source,java]
+----
+public class SomeClass
+ extends SomeOtherClass { // \<1>
+ public static void main(String[] args) { // \<2>
+ ...
+ }
+}
+----
+<1> inherits from `SomeOtherClass`
+<2> entry point into the program
+....
+
+will render as:
+
+[source,java]
+----
+public class SomeClass
+ extends SomeOtherClass { //<1>
+ public static void main(String[] args) { //<2>
+ ...
+ }
+}
+----
+<1> inherits from `SomeOtherClass`
+<2> entry point into the program
+
+
+and
+
+....
+[source,xml]
+----
+<a>
+ <b c="foo"> \<!--1-->
+</a>
+----
+<1> some comment
+....
+
+renders as:
+
+[source,xml]
+----
+<a>
+ <b c="foo"> <!--1-->
+</a>
+----
+<1> some comment
+
+
+It's also possible to include source code snippets; see the guides linked previously
+
+
+[[__markup-docs_asciidoc_images]]
+== Images
+
+Use the `image:` macro to reference images.
+For example:
+
+....
+image:_images/vscode.png[]
+....
+
+will render as:
+
+image:_images/vscode.png[]
+
+
+to make the image clickable, add in the `link` attribute:
+
+....
+image:_images/vscode.png[link="_images/vscode.png"]
+....
+
+will render as:
+
+image:_images/vscode.png[link="_images/vscode.png"]
+
+
+to make the image clickable, add in the `link` attribute:
+
+
+It's also possible to specify the width using `scaledwidth` (for PDF/HTML) or `width` and `height` (for HTML only).
+
+
+
+[[__markup-docs_asciidoc_child-documents]]
+== Child Documents
+
+
+Use the `include:` macro to break up a document into multiple sections.
+
+For example, the xref:../../setting-up/concepts/concepts.adoc#[concepts] document is broken into several files:
+
+....
+concepts.adoc
+_concepts_why-a-new-platform.adoc
+_concepts_ci-as-a-service.adoc
+_concepts_git-intro.adoc
+....
+
+and so on.
+
+These are included using:
+
+[source,asciidoc]
+----
+\include::_concepts_why-a-new-platform.adoc[leveloffset=+1]
+\include::_concepts_ci-as-a-service.adoc[leveloffset=+1]
+\include::_concepts_git-intro.adoc[leveloffset=+1]
+----
+
+The `leveloffset=+1` means that each included file's heading levels are automatically adjusted.
+The net effect is that all documents can and should use heading 1 as their top-level.
+
+Child documents should have '_' as prefix.
+This ensures that they are ignored by the build; only .html and PDF files are created for the top-level parent documents.
+
+The CI/documentation platform also supports the "Improve this doc" button, allowing any document to be edited via the TFS portal; very useful for small fixes.
+To make this work, it relies upon the following naming conventions:
+
+* every document should have an id anchor for its level heading corresponding to its file name
+* every child document's name should be an '_ followed by the name of its parent.
+
+For example, `concepts.adoc` is:
+
+[source,asciidoc]
+----
+[[concepts]]
+= Concepts
+...
+----
+
+while its child document `_concepts_why-a-new-platform.adoc` starts with:
+
+[source,asciidoc]
+----
+[[_concepts_why-a-new-platform]]
+= Why a new platform?
+...
+----
+
+In general, we use '_' to separate out the logical hierarchy:
+
+[source]
+----
+xxx-xxx/xxx-xxx.adoc
+ _xxx-xxx_ppp-ppp.adoc
+ _xxx-xxx_qqq-qqq.adoc
+ _xxx-xxx_qqq-qqq_mmm-mmm.adoc
+ _xxx-xxx_qqq-qqq_nnn-nnn.adoc
+----
+
+Any referenced images should be in subdirectories of the `_images` directory:
+
+[source]
+----
+xxx-xxx/_images/.
+ /ppp-ppp/.
+ /qqq-qqq/.
+ /mmm-mmm
+ /nnn-nnn
+----
+
+
+
+[[__markup-docs_asciidoc_metadata]]
+== Metadata
+
+The top-level document must include the `_basedir` attribute; this points to the parent directory `src/main/asciidoc`.
+This attribute is set immediately after the top-level heading.
+
+In addition, the `:toc:` adds a table of contents.
+
+For example, the `setting-up/concepts/concepts.adoc` file starts:
+
+[source,asciidoc]
+----
+[[concepts]]
+= Concepts
+:_basedir: ../../
+:toc: right
+...
+----
+
+
+
+[[__markup-docs_asciidoc_uml]]
+== UML diagrams
+
+Asciidoctor includes support for the link:http://plantuml.com/[plantuml], allowing simple UML diagrams to be easily sketched.
+
+For example:
+
+....
+[plantuml,_images/mydiagram,png]
+--
+class Car
+
+Driver - Car : drives >
+Car *- Wheel : have 4 >
+Car -- Person : < owns
+--
+....
+
+renders as:
+
+[plantuml,_images/mydiagram,png]
+--
+class Car
+
+Driver - Car : drives >
+Car *- Wheel : have 4 >
+Car -- Person : < owns
+--
+
+
+
+
+[[__markup-docs_asciidoc_ditaa]]
+== Ditaa diagrams
+
+Asciidoctor includes support for the link:http://ditaa.sourceforge.net/[ditaa], allowing boxes-and-lines diagrams to be easily sketched.
+
+For example:
+
+....
+[ditaa]
+----
+ +--------+ +-------+ +-------+
+ | | --+ ditaa +--> | |
+ | Text | +-------+ |diagram|
+ |Document| |!magic!| | |
+ | {d}| | | | |
+ +---+----+ +-------+ +-------+
+ : ^
+ | Lots of work |
+ +-------------------------+
+----
+....
+
+renders as:
+
+[ditaa]
+----
+ +--------+ +-------+ +-------+
+ | | --+ ditaa +--> | |
+ | Text | +-------+ |diagram|
+ |Document| |!magic!| | |
+ | {d}| | | | |
+ +---+----+ +-------+ +-------+
+ : ^
+ | Lots of work |
+ +-------------------------+
+----
+
+
+[[__markup-docs_asciidoc_graphviz]]
+== Graphviz diagrams
+
+
+Asciidoctor includes support for the link:http://ditaa.sourceforge.net/[ditaa], allowing boxes-and-lines diagrams to be easily sketched.
+
+For example:
+
+....
+[graphviz]
+----
+digraph automata_0 {
+ size ="8.5, 11";
+ node [shape = circle];
+ 0 [ style = filled, color=lightgrey ];
+ 2 [ shape = doublecircle ];
+ 0 -> 2 [ label = "a " ];
+ 0 -> 1 [ label = "other " ];
+ 1 -> 2 [ label = "a " ];
+ 1 -> 1 [ label = "other " ];
+ 2 -> 2 [ label = "a " ];
+ 2 -> 1 [ label = "other " ];
+ "Machine: a" [ shape = plaintext ];
+}
+----
+....
+
+renders as:
+
+[graphviz]
+----
+digraph automata_0 {
+ size ="8.5, 11";
+ node [shape = circle];
+ 0 [ style = filled, color=lightgrey ];
+ 2 [ shape = doublecircle ];
+ 0 -> 2 [ label = "a " ];
+ 0 -> 1 [ label = "other " ];
+ 1 -> 2 [ label = "a " ];
+ 1 -> 1 [ label = "other " ];
+ 2 -> 2 [ label = "a " ];
+ 2 -> 1 [ label = "other " ];
+ "Machine: a" [ shape = plaintext ];
+}
+----
+
+[IMPORTANT]
+====
+This requires graphviz to be installed and the `dot.exe` on the PATH.
+Alternatively, specify the location, eg using:
+
+....
+:graphvizdot: c:\Program Files (x86)\Graphviz2.38\bin\dot.exe
+....
+====
+
http://git-wip-us.apache.org/repos/asf/isis/blob/d0edbd42/adocs/documentation/src/main/asciidoc/guides/_dg_asciidoc-templates.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_dg_asciidoc-templates.adoc b/adocs/documentation/src/main/asciidoc/guides/_dg_asciidoc-templates.adoc
index cf641ad..39352c9 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_dg_asciidoc-templates.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_dg_asciidoc-templates.adoc
@@ -11,51 +11,64 @@ This appendix lists the (IntelliJ) live templates available for xref:dg.adoc#_dg
In the examples below the text `xxx`, `yyy`, `zzz` are correspond to template variables (ie placeholders).
-== Callouts
+== Admonitions (Callouts)
-The Asciidoctor terminology is an "admonition".
-[cols="1,4,2a", options="header"]
+[cols="1,4a,2a", options="header"]
|===
| Abbrev.
| Produces
| Example
|`adadmimportant`
-| `[IMPORTANT] +
-==== +
-xxx +
-====`
+|....
+[IMPORTANT]
+====
+xxx
+====
+....
+
|[IMPORTANT]
====
xxx
====
|`adadmnote`
-| `[NOTE] +
-==== +
-xxx +
-====`
+|....
+[NOTE]
+====
+xxx
+====
+....
+
|[NOTE]
====
xxx
====
+....
|`adadmtip`
-| `[TIP] +
-==== +
-xxx +
-====`
+|....
+[TIP]
+====
+xxx
+====
+....
+
|[TIP]
====
xxx
====
+....
|`adadmwarning`
-| `[WARNING] +
-==== +
-xxx +
-====`
+|....
+[WARNING]
+====
+xxx
+====
+....
+
|[WARNING]
====
xxx
@@ -75,11 +88,16 @@ Add as a placeholder for documentation still to be written or which is work-in-p
| Example
|`adtodo`
-|pass:[<pre>NOTE: TODO</pre>]
+|....
+NOTE: TODO
+....
+
|NOTE: TODO
|`adwip`
-|pass:[<pre>NOTE: WIP - xxx</pre>]
+|....
+NOTE: WIP - xxx
+....
where:
@@ -104,7 +122,7 @@ Cross-references (links) to the various guides
|`adcgcom`
-|pass:[<pre>xref:cgcom.adoc#xxx[ttt\]</pre>]
+|`\xref:cgcom.adoc#xxx[ttt]`
a hyperlink to a bookmark within the committers' guide, where:
@@ -113,10 +131,10 @@ a hyperlink to a bookmark within the committers' guide, where:
for example:
-pass:[<pre>xref:dg.adoc#_cgcom_cutting-a-release[Cutting a release\]</pre>]
+`\xref:dg.adoc#_cgcom_cutting-a-release[Cutting a release\]`
|`addg`
-|pass:[<pre>xref:dg.adoc#xxx[ttt\]</pre>]
+|`\xref:dg.adoc#xxx[ttt]`
a hyperlink to a bookmark within the developers' guide, where:
@@ -125,14 +143,14 @@ a hyperlink to a bookmark within the developers' guide, where:
for example:
-pass:[<pre>xref:dg.adoc#_dg_asciidoc-templates[Asciidoc templates\]</pre>]
+`\xref:dg.adoc#_dg_asciidoc-templates[Asciidoc templates\]`
|xref:dg.adoc#_dg_asciidoc-templates[Asciidoc templates]
|`adrgant`
-|pass:[<pre>xref:rgant.adoc#xxx[ttt\]</pre>]
+|`\xref:rgant.adoc#xxx[ttt]`
a hyperlink to a bookmark within the reference guide for annotations, where:
@@ -141,14 +159,14 @@ a hyperlink to a bookmark within the reference guide for annotations, where:
for example:
-pass:[<pre>xref:rgant.adoc#_rgant-aaa_main[Core annotations\]</pre>]
+`\xref:rgant.adoc#_rgant-aaa_main[Core annotations]`
|xref:rgant.adoc#_rgant-aaa_main[Core annotations]
|`adrgcfg`
-|pass:[<pre>xref:rgcfg.adoc#xxx[ttt\]</pre>]
+|`\xref:rgcfg.adoc#xxx[ttt]`
a hyperlink to a bookmark within the reference guide for configuration properties guide, where:
@@ -157,14 +175,14 @@ a hyperlink to a bookmark within the reference guide for configuration propertie
for example:
-pass:[<pre>xref:rgcfg.adoc#_rgcfg_configuring-core[Configuring Core\]</pre>]
+`\xref:rgcfg.adoc#_rgcfg_configuring-core[Configuring Core]`
|xref:rgcfg.adoc#_rgcfg_configuring-core[Configuring Core]
|`adrgcms`
-|pass:[<pre>xref:rgcms.adoc#xxx[ttt\]</pre>]
+|`\xref:rgcms.adoc#xxx[ttt]`
a hyperlink to a bookmark within the reference guide for classes, methods and schema, where:
@@ -173,14 +191,14 @@ a hyperlink to a bookmark within the reference guide for classes, methods and sc
for example:
-pass:[<pre>xref:rgcms.adoc#_rgcms_classes_super_AbstractService[`AbstractService`\]</pre>]
+`\xref:rgcms.adoc#_rgcms_classes_super_AbstractService[`AbstractService`]`
|xref:rgcms.adoc#_rgcms_classes_super_AbstractService[`AbstractService`]
|`adrgsvc`
-|pass:[<pre>xref:rgsvc.adoc#xxx[ttt\]</pre>]
+|`\xref:rgsvc.adoc#xxx[ttt]`
a hyperlink to a bookmark within the reference guide for domain services, where:
@@ -189,14 +207,14 @@ a hyperlink to a bookmark within the reference guide for domain services, where:
for example:
-pass:[<pre>xref:rgsvc.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest` bootstrapping\]</pre>]
+`\xref:rgsvc.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest` bootstrapping]`
-|xref:xref:rgsvc.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest` bootstrapping]
+|xref:rgsvc.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest` bootstrapping]
|`adrgmvn`
-|pass:[<pre>xref:rgmvn.adoc#xxx[ttt\]</pre>]
+|`\xref:rgmvn.adoc#xxx[ttt]`
a hyperlink to a bookmark within the reference guide for the maven plugin, where:
@@ -205,14 +223,14 @@ a hyperlink to a bookmark within the reference guide for the maven plugin, where
for example:
-pass:[<pre>xref:rgmvn.adoc#_rgmvn_validate[validate goal\]</pre>]
+`\xref:rgmvn.adoc#_rgmvn_validate[validate goal]`
|xref:rgmvn.adoc#_rgmvn_validate[validate goal]
|`adrgna`
-|pass:[<pre>xref:rgant.adoc#_rgant-xxx[`@xxx`]</pre>]
+|`\xref:rgant.adoc#_rgant-xxx[`@xxx`]`
a hyperlink to the "man page" for an annotation within the reference guide for annotations, where:
@@ -220,14 +238,14 @@ a hyperlink to the "man page" for an annotation within the reference guide for a
for example:
-pass:[<pre>xref:rgant.adoc#_rgant-Action[`@Action`\]</pre>]
+`\xref:rgant.adoc#_rgant-Action[`@Action`]`
|xref:rgant.adoc#_rgant-Action[`@Action`]
|`adrgnt`
-|pass:[<pre>xref:rgant.adoc#_rgant-xxx_ttt[`@xxx#ttt()`]</pre>]
+|`\xref:rgant.adoc#_rgant-xxx_ttt[`@xxx#ttt()`]`
a hyperlink to the "man page" for the specific attribute (field) of an annotation within the reference guide for annotations, where:
@@ -236,14 +254,14 @@ a hyperlink to the "man page" for the specific attribute (field) of an annotatio
for example:
-pass:[<pre>xref:rgant.adoc#_rgant-Action_semantics[`@Action#semantics()`\]</pre>]
+`\xref:rgant.adoc#_rgant-Action_semantics[`@Action#semantics()`]`
|xref:rgant.adoc#_rgant-Action_semantics[`@Action#semantics()`]
|`adrgsa`
-|pass:[<pre></pre>]
+|`\xref:rgsvc.adoc#_rgsvc_api_xxx[`xxx`]`
a hyperlink to the "man page" for an (API) domain service within the reference guide for domain services, where:
@@ -251,14 +269,14 @@ a hyperlink to the "man page" for an (API) domain service within the reference g
for example:
-pass:[<pre>xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`\]</pre>]
+`\xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`]`
|xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`]
|`adrgss`
-|pass:[<pre></pre>]
+|`\xref:rgsvc.adoc#_rgsvc_spi_xxx[`xxx`]`
a hyperlink to the "man page" for an (SPI) domain service within the reference guide for domain services, where:
@@ -266,14 +284,15 @@ a hyperlink to the "man page" for an (SPI) domain service within the reference g
for example:
-pass:[<pre>xref:rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`\]</pre>]
+`\xref:rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`]`
+
|xref:rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`]
|`adugfun`
-|pass:[<pre>xref:ugfun.adoc#xxx[ttt\]</pre>]
+|`\xref:ugfun.adoc#xxx[ttt]`
a hyperlink to a bookmark within the fundamentals users' guide, where:
@@ -282,7 +301,7 @@ a hyperlink to a bookmark within the fundamentals users' guide, where:
for example:
-pass:[<pre>xref:ugfun.adoc#_ugfun_core-concepts[Core concepts\]</pre>]
+`\xref:ugfun.adoc#_ugfun_core-concepts[Core concepts]`
|xref:ugfun.adoc#_ugfun_core-concepts[Core concepts]
@@ -290,7 +309,7 @@ pass:[<pre>xref:ugfun.adoc#_ugfun_core-concepts[Core concepts\]</pre>]
|`adugvw`
-|pass:[<pre>xref:ugvw.adoc#xxx[ttt\]</pre>]
+|`\xref:ugvw.adoc#xxx[ttt]`
A hyperlink to a bookmark within the Wicket viewer guide, where:
@@ -299,13 +318,13 @@ A hyperlink to a bookmark within the Wicket viewer guide, where:
for example:
-pass:[<pre>xref:ugvw.adoc#_ugvw_customisation[Customisation\]</pre>]
+`\xref:ugvw.adoc#_ugvw_customisation[Customisation]`
|xref:ugvw.adoc#_ugvw_customisation[Customisation]
|`adugvro`
-|pass:[<pre>xref:ugvro.adoc#xxx[ttt\]</pre>]
+|`\xref:ugvro.adoc#xxx[ttt]`
A hyperlink to a bookmark within the Restful Objects viewer guide, where:
@@ -314,14 +333,14 @@ A hyperlink to a bookmark within the Restful Objects viewer guide, where:
for example:
-pass:[<pre>xref:ugvro.adoc#_ugvro_ro-spec[RestfulObjects specification\]</pre>]
+`\xref:ugvro.adoc#_ugvro_ro-spec[RestfulObjects specification]`
|xref:ugvro.adoc#_ugvro_ro-spec[RestfulObjects specification]
|`adugsec`
-|pass:[<pre>xref:ugsec.adoc#xxx[ttt\]</pre>]
+|`\xref:ugsec.adoc#xxx[ttt]`
A hyperlink to a bookmark within the Secrurity guide, where:
@@ -330,13 +349,13 @@ A hyperlink to a bookmark within the Secrurity guide, where:
for example:
-pass:[<pre>xref:ugsec.adoc#_ugsec_shiro-caching[Caching and other Shiro Features\]</pre>]
+`\xref:ugsec.adoc#_ugsec_shiro-caching[Caching and other Shiro Features]`
|xref:ugsec.adoc#_ugsec_shiro-caching[Caching and other Shiro Features]
|`adugtst`
-|pass:[<pre>xref:ugtst.adoc#xxx[ttt\]</pre>]
+|`\xref:ugtst.adoc#xxx[ttt]`
A hyperlink to a bookmark within the Testing guide, where:
@@ -345,13 +364,13 @@ A hyperlink to a bookmark within the Testing guide, where:
for example:
-pass:[<pre>xref:ugtst.adoc#_ugtst_bdd-spec-support[BDD Spec Support\]</pre>]
+`\xref:ugtst.adoc#_ugtst_bdd-spec-support[BDD Spec Support]`
|xref:ugtst.adoc#_ugtst_bdd-spec-support[BDD Spec Support]
|`adugbtb`
-|pass:[<pre>xref:ugbtb.adoc#xxx[ttt\]</pre>]
+|`\xref:ugbtb.adoc#xxx[ttt]`
A hyperlink to a bookmark within the 'Beyond the Basics' user guide, where:
@@ -360,7 +379,7 @@ A hyperlink to a bookmark within the 'Beyond the Basics' user guide, where:
for example:
-pass:[<pre>xref:ugbtb.adoc#_ugbtb_deployment_externalized-configuration[Externalized Configuration\]</pre>]
+`\xref:ugbtb.adoc#_ugbtb_deployment_externalized-configuration[Externalized Configuration]`
|xref:ugbtb.adoc#_ugbtb_deployment_externalized-configuration[Externalized Configuration]
@@ -384,7 +403,7 @@ Links to (non-ASF) link:http://isisaddons.org[Isis Addons]
|`adlinkaddons`
-|pass:[<pre>(non-ASF) link:http://isisaddons.org[Isis Addons\]</pre>]
+|`(non-ASF) \link:\http://isisaddons.org[[Isis Addons]]`
link to the Isis Addons website.
@@ -393,7 +412,7 @@ link to the Isis Addons website.
|`adlinkaddonsapp`
-|pass:[<pre>(non-ASF) http://github.com/isisaddons/isis-app-xxx[Isis addons' xxx]</pre>]
+|`(non-ASF) \link:\http://github.com/isisaddons/isis-app-xxx[[Isis addons' xxx]]`
link to the github repo for an example app from the Isis addons; where:
@@ -401,14 +420,14 @@ link to the github repo for an example app from the Isis addons; where:
for example:
-pass:[<pre>(non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp\]</pre>]
+pass:[<pre>(non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp]`
|(non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp]
|`adlinkaddonsmodule`
-|pass:[<pre></pre>]
+|`(non-ASF) \http://github.com/isisaddons/isis-module-xxx[[Isis addons' xxx]] module`
link to the github repo for a module from the Isis addons; where:
@@ -416,14 +435,14 @@ link to the github repo for a module from the Isis addons; where:
for example:
-pass:[<pre>(non-ASF) http://github.com/isisaddons/isis-module-security[Isis addons' security\] module</pre>]
+`(non-ASF) \http://github.com/isisaddons/isis-module-security[[Isis addons' security]] module`
|(non-ASF) http://github.com/isisaddons/isis-module-security[Isis addons' security] module
|`adlinkaddonswicket`
-|pass:[<pre></pre>]
+|`(non-ASF) \http://github.com/isisaddons/isis-wicket-xxx[[Isis addons' xxx]] wicket extension`
link to the github repo for a wicket UI component from the Isis addons; where:
@@ -431,7 +450,7 @@ link to the github repo for a wicket UI component from the Isis addons; where:
for example:
-pass:[<pre>(non-ASF) http://github.com/isisaddons/isis-wicket-gmap3[Isis addons' gmap3 \] wicket extension</pre>]
+`(non-ASF) \http://github.com/isisaddons/isis-wicket-gmap3[[Isis addons' gmap3]] wicket extension`
|(non-ASF) http://github.com/isisaddons/isis-wicket-gmap3[Isis addons' gmap3 ] wicket extension
@@ -450,10 +469,12 @@ pass:[<pre>(non-ASF) http://github.com/isisaddons/isis-wicket-gmap3[Isis addons'
| Example
|`adsrcjava`
-|`[source,java] +
----- +
-xxx +
-----`
+|....
+[source,java]
+----
+xxx
+----
+....
where:
@@ -474,10 +495,12 @@ public class Foo {
|`adsrcjavascript`
-|`[source,javascript] +
----- +
-xxx +
-----`
+|....
+[source,javascript]
+----
+xxx
+----
+....
where:
@@ -498,10 +521,12 @@ $(document).ready(function() {
|
|`adsrcother`
-|`[source,nnn] +
----- +
-xxx +
-----`
+|....
+[source,nnn]
+----
+xxx
+---
+....
where:
@@ -517,10 +542,13 @@ where:
|
|`adsrcxml`
-|`[source,javascript] +
----- +
-xxx +
-----`
+|....
+[source,javascript]
+----
+xxx
+----
+....
+
where:
@@ -552,7 +580,7 @@ where:
| Example
|`adimgfile`
-|pass:[<pre>image::{_imagesdir}xxx/yyy.png[width="WWWpx",link="{_imagesdir}xxx/yyy.png"\]</pre>]
+|`\image:{_imagesdir}xxx/yyy.png[width="WWWpx",link="{_imagesdir}xxx/yyy.png"]`
embeds specified image, where:
@@ -562,9 +590,9 @@ embeds specified image, where:
for example:
-pass:[<pre>image::{_imagesdir}wicket-viewer/layouts/estatio-Lease.png[width="300px",link="{_imagesdir}wicket-viewer/layouts/estatio-Lease.png"\]</pre>]
+`\image:{_imagesdir}wicket-viewer/layouts/estatio-Lease.png[width="300px",link="{_imagesdir}wicket-viewer/layouts/estatio-Lease.png"]`
-|image::{_imagesdir}wicket-viewer/layouts/estatio-Lease.png[width="300px",link="{_imagesdir}wicket-viewer/layouts/estatio-Lease.png"]
+|image:{_imagesdir}wicket-viewer/layouts/estatio-Lease.png[width="300px",link="{_imagesdir}wicket-viewer/layouts/estatio-Lease.png"]
@@ -574,7 +602,7 @@ pass:[<pre>image::{_imagesdir}wicket-viewer/layouts/estatio-Lease.png[width="300
|`adimgurl`
-|pass:[<pre>image::xxx[width="WWWpx",link="xxx"\]</pre>]
+|`\image:xxx[width="WWWpx",link="xxx"]`
embeds image from specified URL, where:
@@ -605,7 +633,7 @@ Embedded youtube screencasts. (Don't use these in guides, as they cannot be ren
| Example
|`adyoutube`
-|pass:[<pre>video::xxx[youtube,width="WWWpx",height="HHHpx"\]</pre>]
+|`video:xxx[youtube,width="WWWpx",height="HHHpx"]`
where:
@@ -615,7 +643,7 @@ where:
for example:
-pass:[<pre>video::bj8735nBRR4[youtube,width="210px",height="118px"\] </pre>]
+`video::bj8735nBRR4[youtube,width="210px",height="118px"]`
|video::bj8735nBRR4[youtube,width="210px",height="118px"]
@@ -652,7 +680,7 @@ pass:[<pre>video::bj8735nBRR4[youtube,width="210px",height="118px"\] </pre>]
| Example
|`adai`
-|pass:[<pre>Apache Isis</pre>] +
+|`Apache Isis` +
That is, the literal text "Apache Isis".
|Apache Isis
@@ -660,7 +688,7 @@ That is, the literal text "Apache Isis".
|`adlink`
-|pass:[<pre>link:xxx[ttt\]</pre>]
+|`\link:xxx[ttt]`
, where:
@@ -669,7 +697,7 @@ That is, the literal text "Apache Isis".
for example:
-pass:[<pre>link:http://isis.apache.org[Apache Isis website\]</pre>]
+`\link:\http://isis.apache.org[[Apache Isis website]]`
|link:http://isis.apache.org[Apache Isis website]
@@ -677,7 +705,7 @@ pass:[<pre>link:http://isis.apache.org[Apache Isis website\]</pre>]
|`adanchany`
-|pass:[<pre>= anchor:[xxx\]</pre>]
+|`= anchor:[xxx]`
defines an inline anchor to any heading, where:
@@ -685,18 +713,20 @@ defines an inline anchor to any heading, where:
For example:
-pass:[<pre>= anchor:[_ugfun_i18n\] Internationalization</pre>]
+`= anchor:[_ugfun_i18n] Internationalization`
An alternative (more commonly used in our documentation) is to use the `[[...]]` directly above the heading:
-pass:[<pre>[[_ugfun_i18n\]\]
-= Internationalization</pre>]
+....
+[[_ugfun_i18n]]
+= Internationalization
+....
|
|`adxrefany`
-|pass:[<pre>xref:[xxx\]</pre>]
+|`\xref:[xxx]`
cross-reference to any document/anchor, where:
@@ -706,15 +736,14 @@ cross-reference to any document/anchor, where:
|`adfootnote`
-|pass:[<pre>.footnote:[\]</pre>]
+|`\footnote:[xxx]`
defines a footnote
-|.footnote:[this is a footnote]
-
+|footnote:[this is a footnote]
-|===
+|===
http://git-wip-us.apache.org/repos/asf/isis/blob/d0edbd42/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_collections.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_collections.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_collections.adoc
index fe7cfdf..12ccf50 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_collections.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_how-tos_class-structure_collections.adoc
@@ -55,7 +55,7 @@ public class ParentObject
<1> indicates a bidirectional association; the foreign key pointing back to the `Parent` will be in the table for `ChildObject`
<2> disable cascade delete
<3> (not actually required in this case, because no attributes are set, but acts as a useful reminder that this collection will be rendered in the UI by Apache Isis)
-<3> uses a `SortedSet` (as opposed to some other collection type; discussion below)
+<4> uses a `SortedSet` (as opposed to some other collection type; discussion below)
while in the child object you will have:
http://git-wip-us.apache.org/repos/asf/isis/blob/d0edbd42/adocs/documentation/src/main/asciidoc/guides/cgcom.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/cgcom.adoc b/adocs/documentation/src/main/asciidoc/guides/cgcom.adoc
index 146bd96..ce6218b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/cgcom.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/cgcom.adoc
@@ -22,7 +22,7 @@ The user guides available are:
* xref:ugfun.adoc#[Fundamentals]
* xref:ugvw.adoc#[Wicket viewer]
* xref:ugvro.adoc#[Restful Objects viewer]
-* xref:ugdno.adoc#[DataNucleus object store]
+* xref:ugodn.adoc#[DataNucleus object store]
* xref:ugsec.adoc#[Security]
* xref:ugtst.adoc#[Testing]
* xref:ugbtb.adoc#[Beyond the Basics]
http://git-wip-us.apache.org/repos/asf/isis/blob/d0edbd42/adocs/documentation/src/main/asciidoc/guides/dg.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg.adoc b/adocs/documentation/src/main/asciidoc/guides/dg.adoc
index 22827b8..efd8065 100644
--- a/adocs/documentation/src/main/asciidoc/guides/dg.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/dg.adoc
@@ -30,7 +30,7 @@ The user guides available are:
* xref:ugfun.adoc#[Fundamentals]
* xref:ugvw.adoc#[Wicket viewer]
* xref:ugvro.adoc#[Restful Objects viewer]
-* xref:ugdno.adoc#[DataNucleus object store]
+* xref:ugodn.adoc#[DataNucleus object store]
* xref:ugsec.adoc#[Security]
* xref:ugtst.adoc#[Testing]
* xref:ugbtb.adoc#[Beyond the Basics]
@@ -62,6 +62,7 @@ include::_dg_contributing.adoc[leveloffset=+1]
include::_dg_git-cookbook.adoc[leveloffset=+1]
include::_dg_working-with-many-repos.adoc[leveloffset=+1]
+include::_dg_asciidoc-syntax.adoc[leveloffset=+1]
include::_dg_asciidoc-templates.adoc[leveloffset=+1]
include::_dg_project-lombok.adoc[leveloffset=+1]
include::_dg_agilej.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/d0edbd42/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 bad0833..bbc69ea 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant.adoc
@@ -22,7 +22,7 @@ The user guides available are:
* xref:ugfun.adoc#[Fundamentals]
* xref:ugvw.adoc#[Wicket viewer]
* xref:ugvro.adoc#[Restful Objects viewer]
-* xref:ugdno.adoc#[DataNucleus object store]
+* xref:ugodn.adoc#[DataNucleus object store]
* xref:ugsec.adoc#[Security]
* xref:ugtst.adoc#[Testing]
* xref:ugbtb.adoc#[Beyond the Basics]
http://git-wip-us.apache.org/repos/asf/isis/blob/d0edbd42/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 d0a1fc8..5e63ac8 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcfg.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcfg.adoc
@@ -38,7 +38,7 @@ The user guides available are:
* xref:ugfun.adoc#[Fundamentals]
* xref:ugvw.adoc#[Wicket viewer]
* xref:ugvro.adoc#[Restful Objects viewer]
-* xref:ugdno.adoc#[DataNucleus object store]
+* xref:ugodn.adoc#[DataNucleus object store]
* xref:ugsec.adoc#[Security]
* xref:ugtst.adoc#[Testing]
* xref:ugbtb.adoc#[Beyond the Basics]
http://git-wip-us.apache.org/repos/asf/isis/blob/d0edbd42/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 a3b3ac5..190fd12 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms.adoc
@@ -25,7 +25,7 @@ The user guides available are:
* xref:ugfun.adoc#[Fundamentals]
* xref:ugvw.adoc#[Wicket viewer]
* xref:ugvro.adoc#[Restful Objects viewer]
-* xref:ugdno.adoc#[DataNucleus object store]
+* xref:ugodn.adoc#[DataNucleus object store]
* xref:ugsec.adoc#[Security]
* xref:ugtst.adoc#[Testing]
* xref:ugbtb.adoc#[Beyond the Basics]
http://git-wip-us.apache.org/repos/asf/isis/blob/d0edbd42/adocs/documentation/src/main/asciidoc/guides/rgfis.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgfis.adoc b/adocs/documentation/src/main/asciidoc/guides/rgfis.adoc
index c703ccc..a22dc20 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgfis.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgfis.adoc
@@ -30,7 +30,7 @@ The user guides available are:
* xref:ugfun.adoc#[Fundamentals]
* xref:ugvw.adoc#[Wicket viewer]
* xref:ugvro.adoc#[Restful Objects viewer]
-* xref:ugdno.adoc#[DataNucleus object store]
+* xref:ugodn.adoc#[DataNucleus object store]
* xref:ugsec.adoc#[Security]
* xref:ugtst.adoc#[Testing]
* xref:ugbtb.adoc#[Beyond the Basics]
http://git-wip-us.apache.org/repos/asf/isis/blob/d0edbd42/adocs/documentation/src/main/asciidoc/guides/rgmvn.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgmvn.adoc b/adocs/documentation/src/main/asciidoc/guides/rgmvn.adoc
index 730ebc7..313dc83 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgmvn.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgmvn.adoc
@@ -21,7 +21,7 @@ The user guides available are:
* xref:ugfun.adoc#[Fundamentals]
* xref:ugvw.adoc#[Wicket viewer]
* xref:ugvro.adoc#[Restful Objects viewer]
-* xref:ugdno.adoc#[DataNucleus object store]
+* xref:ugodn.adoc#[DataNucleus object store]
* xref:ugsec.adoc#[Security]
* xref:ugtst.adoc#[Testing]
* xref:ugbtb.adoc#[Beyond the Basics]
http://git-wip-us.apache.org/repos/asf/isis/blob/d0edbd42/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 fbadbf3..d82797d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc.adoc
@@ -25,7 +25,7 @@ The user guides available are:
* xref:ugfun.adoc#[Fundamentals]
* xref:ugvw.adoc#[Wicket viewer]
* xref:ugvro.adoc#[Restful Objects viewer]
-* xref:ugdno.adoc#[DataNucleus object store]
+* xref:ugodn.adoc#[DataNucleus object store]
* xref:ugsec.adoc#[Security]
* xref:ugtst.adoc#[Testing]
* xref:ugbtb.adoc#[Beyond the Basics]
http://git-wip-us.apache.org/repos/asf/isis/blob/d0edbd42/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 07fb02e..425c89b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb.adoc
@@ -23,7 +23,7 @@ The user guides available are:
* xref:ugfun.adoc#[Fundamentals]
* xref:ugvw.adoc#[Wicket viewer]
* xref:ugvro.adoc#[Restful Objects viewer]
-* xref:ugdno.adoc#[DataNucleus object store]
+* xref:ugodn.adoc#[DataNucleus object store]
* xref:ugsec.adoc#[Security]
* xref:ugtst.adoc#[Testing]
* xref:ugbtb.adoc#[Beyond the Basics] (this guide)
http://git-wip-us.apache.org/repos/asf/isis/blob/d0edbd42/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
index cf0c2c6..c5c771e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun.adoc
@@ -25,7 +25,7 @@ The user guides available are:
* xref:ugfun.adoc#[Fundamentals] (this guide)
* xref:ugvw.adoc#[Wicket viewer]
* xref:ugvro.adoc#[Restful Objects viewer]
-* xref:ugdno.adoc#[DataNucleus object store]
+* xref:ugodn.adoc#[DataNucleus object store]
* xref:ugsec.adoc#[Security]
* xref:ugtst.adoc#[Testing]
* xref:ugbtb.adoc#[Beyond the Basics]
http://git-wip-us.apache.org/repos/asf/isis/blob/d0edbd42/adocs/documentation/src/main/asciidoc/guides/ugodn.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn.adoc
index 5272d25..1a9c6a8 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugodn.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugodn.adoc
@@ -1,4 +1,4 @@
-[[ugdnos]]
+[[ugodn]]
= DataNucleus Object Store
:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the 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: ../
@@ -8,10 +8,11 @@
-[[_ugdnos]]
+[[_ugodn]]
== DataNucleus Object Store
-The DataNucleus Object Store enables domain objects to be persisted to relational as well as NoSQL databases. The object store is implemented using link:http://datanuclues.org[DataNucleus].
+The DataNucleus Object Store enables domain objects to be persisted to relational as well as NoSQL databases.
+The object store is implemented using link:http://datanuclues.org[DataNucleus].
This user guide discuss end-user features, configuration and customization of the DataNucleus object store.
@@ -23,9 +24,6 @@ DataNucleus as a product also supports the JPA API; Apache Isis is likely to als
====
-include::_ugbtb_datanucleus_overriding-jdo-annotations.adoc[leveloffset=+1]
-include::_ugbtb_datanucleus_java8.adoc[leveloffset=+1]
-
=== Other Guides
@@ -37,7 +35,7 @@ The user guides available are:
* xref:ugfun.adoc#[Fundamentals]
* xref:ugvw.adoc#[Wicket viewer]
* xref:ugvro.adoc#[Restful Objects viewer]
-* xref:ugdno.adoc#[DataNucleus object store] (this guide)
+* xref:ugodn.adoc#[DataNucleus object store] (this guide)
* xref:ugsec.adoc#[Security]
* xref:ugtst.adoc#[Testing]
* xref:ugbtb.adoc#[Beyond the Basics]
http://git-wip-us.apache.org/repos/asf/isis/blob/d0edbd42/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 eaf7da9..f4363ba 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugsec.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugsec.adoc
@@ -21,7 +21,7 @@ The user guides available are:
* xref:ugfun.adoc#[Fundamentals]
* xref:ugvw.adoc#[Wicket viewer]
* xref:ugvro.adoc#[Restful Objects viewer]
-* xref:ugdno.adoc#[DataNucleus object store]
+* xref:ugodn.adoc#[DataNucleus object store]
* xref:ugsec.adoc#[Security] (this guide)
* xref:ugtst.adoc#[Testing]
* xref:ugbtb.adoc#[Beyond the Basics]
http://git-wip-us.apache.org/repos/asf/isis/blob/d0edbd42/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 3c4a946..64ed85a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugtst.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugtst.adoc
@@ -26,7 +26,7 @@ The user guides available are:
* xref:ugfun.adoc#[Fundamentals]
* xref:ugvw.adoc#[Wicket viewer]
* xref:ugvro.adoc#[Restful Objects viewer]
-* xref:ugdno.adoc#[DataNucleus object store]
+* xref:ugodn.adoc#[DataNucleus object store]
* xref:ugsec.adoc#[Security]
* xref:ugtst.adoc#[Testing] (this guide)
* xref:ugbtb.adoc#[Beyond the Basics]
http://git-wip-us.apache.org/repos/asf/isis/blob/d0edbd42/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 fa2d30d..a564554 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvro.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvro.adoc
@@ -31,7 +31,7 @@ The user guides available are:
* xref:ugfun.adoc#[Fundamentals]
* xref:ugvw.adoc#[Wicket viewer]
* xref:ugvro.adoc#[Restful Objects viewer] (this guide)
-* xref:ugdno.adoc#[DataNucleus object store]
+* xref:ugodn.adoc#[DataNucleus object store]
* xref:ugsec.adoc#[Security]
* xref:ugtst.adoc#[Testing]
* xref:ugbtb.adoc#[Beyond the Basics]
http://git-wip-us.apache.org/repos/asf/isis/blob/d0edbd42/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 df22832..c5193e2 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw.adoc
@@ -27,7 +27,7 @@ The user guides available are:
* xref:ugfun.adoc#[Fundamentals]
* xref:ugvw.adoc#[Wicket viewer] (this guide)
* xref:ugvro.adoc#[Restful Objects viewer]
-* xref:ugdno.adoc#[DataNucleus object store]
+* xref:ugodn.adoc#[DataNucleus object store]
* xref:ugsec.adoc#[Security]
* xref:ugtst.adoc#[Testing]
* xref:ugbtb.adoc#[Beyond the Basics]
[5/5] isis git commit: ISIS-1521: enhances github_pr.sh script
Posted by da...@apache.org.
ISIS-1521: enhances github_pr.sh script
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/6ed4f3b7
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/6ed4f3b7
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/6ed4f3b7
Branch: refs/heads/master
Commit: 6ed4f3b74d9d78da915e13375427bdb9bba239d5
Parents: c5b0bc3
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Fri Mar 24 07:39:27 2017 +0000
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Fri Mar 24 07:39:27 2017 +0000
----------------------------------------------------------------------
.../guides/_cgcom_merging-a-pull-request.adoc | 20 ++++-
github-pr.sh | 78 ++++++++++++++------
2 files changed, 73 insertions(+), 25 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/6ed4f3b7/adocs/documentation/src/main/asciidoc/guides/_cgcom_merging-a-pull-request.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cgcom_merging-a-pull-request.adoc b/adocs/documentation/src/main/asciidoc/guides/_cgcom_merging-a-pull-request.adoc
index 5e4c4d5..8871a7f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_cgcom_merging-a-pull-request.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_cgcom_merging-a-pull-request.adoc
@@ -58,14 +58,26 @@ The syntax is:
[source,bash]
----
-github-pr.sh isis 1162 31
+github-pr.sh -j 1162 -g 31 [-s] [-p ISIS]
----
where:
-* `isis` is the JIRA project and repo
-* `1162` is the JIRA ticket number
-* `31` is the gthub PR issue number
+* `-j 1162` +
++
+is the JIRA ticket number
+
+* `-g 31` +
++
+is the github PR issue number
+
+* `-s` +
++
+will optionally skip the build and auto-merge
+
+* `-p ISIS` +
++
+optionally overrids the JIRA project (defaults to 'ISIS')
http://git-wip-us.apache.org/repos/asf/isis/blob/6ed4f3b7/github-pr.sh
----------------------------------------------------------------------
diff --git a/github-pr.sh b/github-pr.sh
index a78dee7..422f40b 100644
--- a/github-pr.sh
+++ b/github-pr.sh
@@ -36,25 +36,52 @@ function die {
exit 10
}
+project="ISIS"
+jira_suffix=""
+pr_number=""
+skip_build="false"
#
# validate script args
#
-if [ $# -ne 3 ]; then
- die "usage: github-pr.sh proj nnn pp"
+
+while getopts ":p:j:g:s" opt; do
+ case $opt in
+ p)
+ project=$OPTARG
+ ;;
+ j)
+ jira_suffix=$OPTARG
+ ;;
+ g)
+ pr_number=$OPTARG
+ ;;
+ s)
+ skip_build="true"
+ ;;
+ \?)
+ echo "Invalid option: -$OPTARG" >&2
+ ;;
+ esac
+done
+
+echo ""
+echo "project : $project"
+echo "ASF jira : $jira_suffix"
+echo "github PR : $pr_number"
+echo "skip_build: $skip_build"
+echo ""
+
+if [ "$jira_suffix" == "" -o "$pr_number" == "" ]; then
+ die "usage: github-pr.sh -j nnn -g pp [-s] [-p pppp]"
fi
-project=$1
-jira_suffix=$2
-pr_number=$3
+
project_lower=$(echo $project | tr '[:upper:]' '[:lower:]')
project_upper=$(echo $project | tr '[:lower:]' '[:upper:]')
jira_number="$project_upper-$jira_suffix"
-echo ""
-
-
#
# validate JIRA ticket
#
@@ -127,18 +154,27 @@ echo "Pulling the changes from $repo_clone_url $branch_name_fork"
git pull $repo_clone_url $branch_name_fork
echo ""
-echo "Merged the PR; hit enter to build"
-read
-echo "Building..."
-echo
-mvn clean install -o
-
-echo
-echo
-echo
-echo "If build successful and happy to merge, execute:"
-echo
-echo "git checkout $branch_name_local && git merge --no-ff $branch_name_temp && git branch -d $branch_name_temp"
-echo
+if [ "$skip_build" == "false" ]
+then
+ echo "Merged the PR; hit enter to build"
+ read
+ echo "Building..."
+ echo
+
+ mvn clean install -o
+
+ echo
+ echo
+ echo
+ echo "If build successful and happy to merge, execute:"
+ echo
+ echo "git checkout $branch_name_local && git merge --no-ff $branch_name_temp && git branch -d $branch_name_temp"
+ echo
+else
+ echo
+ echo "Merging..."
+ echo
+ git checkout $branch_name_local && git merge --no-ff $branch_name_temp && git branch -d $branch_name_temp
+fi
[4/5] isis git commit: ISIS-1521: simplifies previewing of asciidoc
websites
Posted by da...@apache.org.
ISIS-1521: simplifies previewing of asciidoc websites
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/c5b0bc3b
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/c5b0bc3b
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/c5b0bc3b
Branch: refs/heads/master
Commit: c5b0bc3bb71fd38d7ad23667de6bcb7f70552789
Parents: ed24fc3
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Fri Mar 24 07:19:49 2017 +0000
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Fri Mar 24 07:19:49 2017 +0000
----------------------------------------------------------------------
adocs/documentation/monitor.rb | 192 -------------------
adocs/documentation/monitor.sh | 2 -
adocs/documentation/play.rb | 24 ---
adocs/documentation/preview-html.sh | 2 +-
adocs/documentation/preview-pdf.sh | 2 +
.../guides/_dg_asciidoc_instant-rebuild.adoc | 18 +-
6 files changed, 7 insertions(+), 233 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/c5b0bc3b/adocs/documentation/monitor.rb
----------------------------------------------------------------------
diff --git a/adocs/documentation/monitor.rb b/adocs/documentation/monitor.rb
deleted file mode 100644
index 6581087..0000000
--- a/adocs/documentation/monitor.rb
+++ /dev/null
@@ -1,192 +0,0 @@
-require 'rubygems'
-require 'pathname'
-require 'fileutils'
-require 'bundler/setup'
-require "slop"
-require 'launchy'
-require 'webrick'
-
-Bundler.require(:default)
-
-include WEBrick
-
-# to (try to) suppress some debugs
-$CELLULOID_DEBUG=false
-$CELLULOID_TEST=false
-
-
-
-#
-# parse cmd line args
-#
-opts = Slop.parse do |o|
- o.int '-p', '--port', 'port (default: 4000)', default: 4000
- o.bool '-x', '--suppress', 'suppress monitoring'
- o.bool '-b', '--browser', 'launch browser'
- o.bool '-h', '--help', 'help'
-end
-
-if opts.help? then
- puts opts
- exit
-end
-
-port = opts[:port]
-
-
-#scriptDir = File.absolute_path File.dirname(__FILE__)
-templateDir = File.absolute_path '../template'
-srcBaseDir = File.absolute_path 'src/main/asciidoc'
-targetBaseDir = File.absolute_path 'target/site'
-
-srcBasePath = Pathname.new srcBaseDir
-targetBasePath = Pathname.new targetBaseDir
-
-
-def process(file,srcBasePath,targetBasePath,templateDir,i,lastTimeGenerated,priming)
-
- workingDir = Dir.pwd
-
- srcDir = File.dirname file
- srcBase = File.basename file
- ext = File.extname file
-
- srcPath = Pathname.new srcDir
- srcRel = srcPath.relative_path_from srcBasePath
-
- targetRelPath = targetBasePath + srcRel
- targetRelDir = File.absolute_path targetRelPath.to_s
-
- Dir.chdir srcDir
- FileUtils.mkdir_p targetRelDir
-
- if ext == ".adoc" then
-
- srcSplit = srcBase.split('_')
- if srcSplit[0].length==0 then
- # handle include files of form
- # _xxx-xxx_yyy-yyy_zzz => xxx-xxx.adoc
- if priming then
- regenerate = ""
- else
- regenerate = srcSplit[1]
- regenerate += ".adoc" unless regenerate.end_with? ".adoc"
- end
- else
- regenerate = srcBase
- end
-
- unless regenerate == "" then
-
- # if regenerated within last 3 seconds, then wait a while
- currentTime = Time.now
- timeSinceLast = currentTime.to_i - lastTimeGenerated.to_i
- timeUntilNext = 3 - timeSinceLast
- if not priming and
- timeUntilNext > 0 then
- puts "skipping before regenerating (3 seconds not yet elapsed)"
- else
-
- cmd = "asciidoctor #{regenerate} --require asciidoctor-diagram --backend html --eruby erb --template-dir '#{templateDir}' --destination-dir='#{targetRelDir}' -a imagesdir='' -a toc=right -a icons=font -a source-highlighter=coderay"
-
- unless priming then
- puts ""
- puts "#{i}: #{cmd}"
- # wait 1 further second for any additional edits
- sleep 1
- end
- system cmd
- lastTimeGenerated=Time.now
- end
- end
- else
- unless File.directory?(srcBase) then
-
- cmd = "cp #{srcBase} #{targetRelDir}"
- unless priming then
- puts ""
- puts "#{i}: #{cmd}"
- end
-
- system cmd
- end
- end
-
- Dir.chdir workingDir
-
- return i+1, lastTimeGenerated
-end
-
-
-if not opts.suppress? then
-
- i=0
- lastTimeGenerated = Time.now - 10
-
- puts ""
- puts ""
- puts ""
- puts "monitoring..."
- puts ""
-
-
- #
- # then continue monitoring all directories
- #
- adocFiles = Dir.glob("src/main/asciidoc/**/*.adoc")
- directories = adocFiles.each{ |f| File.new(f) }.uniq{ |f| File.dirname(f) }.map{ |f| File.dirname(f) }
-
- puts "listening to: #{directories}"
-
- fileListener = Listen.to(directories) do |modified, added, removed|
- unless modified.length==0
- modified.each { |file|
- i,lastTimeGenerated = process file, srcBasePath, targetBasePath, templateDir, i, lastTimeGenerated, false
- }
- end
- unless added.length==0
- added.each { |file|
- i,lastTimeGenerated = process file, srcBasePath, targetBasePath, templateDir, i, lastTimeGenerated, false
- }
- end
- unless removed.length==0
- removed.each { |file|
- #puts "removed #{file}"
- }
- end
- end
- fileListener.start
-end
-
-httpServer = HTTPServer.new(
- :Port => port,
- :DocumentRoot => 'target/site',
- #Logger: WEBrick::Log.new("/dev/null"),
- AccessLog: [],
- )
-trap("INT"){
- httpServer.shutdown
- fileListener.stop
-}
-
-
-
-if opts.browser? then
-
- puts ""
- puts "opening web browser @ http://localhost:#{port}/"
- puts
-
- Launchy.open("http://localhost:#{port}")
-else
- puts ""
- puts "open web browser @ http://localhost:#{port}/"
- puts
-
-end
-
-
-httpServer.start
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/c5b0bc3b/adocs/documentation/monitor.sh
----------------------------------------------------------------------
diff --git a/adocs/documentation/monitor.sh b/adocs/documentation/monitor.sh
deleted file mode 100644
index fc587f5..0000000
--- a/adocs/documentation/monitor.sh
+++ /dev/null
@@ -1,2 +0,0 @@
-#!/usr/bin/env bash
-mvn compile -o && ruby monitor.rb -b
http://git-wip-us.apache.org/repos/asf/isis/blob/c5b0bc3b/adocs/documentation/play.rb
----------------------------------------------------------------------
diff --git a/adocs/documentation/play.rb b/adocs/documentation/play.rb
deleted file mode 100644
index daaaaa1..0000000
--- a/adocs/documentation/play.rb
+++ /dev/null
@@ -1,24 +0,0 @@
-require 'rubygems'
-require 'pathname'
-require 'fileutils'
-require 'bundler/setup'
-require "slop"
-require 'launchy'
-require 'webrick'
-
-Bundler.require(:default)
-
-include WEBrick
-
-# to (try to) suppress some debugs
-$CELLULOID_DEBUG=false
-$CELLULOID_TEST=false
-
-
-
-adocFiles = Dir.glob("src/main/asciidoc/**/*.adoc")
-
-files = adocFiles.each{ |f| File.new(f) }.uniq{ |f| File.dirname(f) }.map{ |f| File.dirname(f) }
-
-puts "listening to: #{files}"
-
http://git-wip-us.apache.org/repos/asf/isis/blob/c5b0bc3b/adocs/documentation/preview-html.sh
----------------------------------------------------------------------
diff --git a/adocs/documentation/preview-html.sh b/adocs/documentation/preview-html.sh
index c1350df..fc7768c 100644
--- a/adocs/documentation/preview-html.sh
+++ b/adocs/documentation/preview-html.sh
@@ -1,2 +1,2 @@
#!/usr/bin/env bash
-mvn compile -o && python -m webbrowser -t http://localhost:8000 && pushd target/site && python -m http.server 8000 && popd
+mvn compile -o && python -m webbrowser -t http://localhost:4000 && pushd target/site && python -m http.server 4000 && popd
http://git-wip-us.apache.org/repos/asf/isis/blob/c5b0bc3b/adocs/documentation/preview-pdf.sh
----------------------------------------------------------------------
diff --git a/adocs/documentation/preview-pdf.sh b/adocs/documentation/preview-pdf.sh
new file mode 100644
index 0000000..618efcd
--- /dev/null
+++ b/adocs/documentation/preview-pdf.sh
@@ -0,0 +1,2 @@
+#!/usr/bin/env bash
+mvn compile -f pom.xml && mvn compile -o && python -m webbrowser -t http://localhost:4000 && pushd target/site && python -m http.server 4000 && popd
http://git-wip-us.apache.org/repos/asf/isis/blob/c5b0bc3b/adocs/documentation/src/main/asciidoc/guides/_dg_asciidoc_instant-rebuild.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_dg_asciidoc_instant-rebuild.adoc b/adocs/documentation/src/main/asciidoc/guides/_dg_asciidoc_instant-rebuild.adoc
index 69328e7..527d93a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_dg_asciidoc_instant-rebuild.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_dg_asciidoc_instant-rebuild.adoc
@@ -38,29 +38,19 @@ To run, we typically just use:
[source,bash]
----
-sh monitor.sh
+sh preview-html.sh
----
-This script simply runs `mvn clean compile && ruby monitor.rb -b`. The `mvn` command performs a clean rebuild of the site, and then the ruby script monitors for any further changes under `src/main/asciidoc`.
+This script just runs `mvn compile` for HTML files only, then calls `python` to start the web browser and run a simple web server (on port 8000).
-The script also starts up a web server on port 4000 so you can review results. If any `.adoc` changes, then the appropriate HTML will be regenerated. And, if any new assets (CSS, images etc) are added, they will be copied across. The `-b` flag passed through means that the script also starts a web browser pointing at the newly generated docs.
-
-The `monitor.rb` script has a couple of other options, use `-h` flag for usage:
+If you want to double-check the PDFs also, then use:
[source,bash]
----
-ruby monitor.rb -h
+sh preview-pdf.sh
----
-which should print:
-[source]
-----
-usage: monitor.rb [options]
- -p, --port port (default: 4000)
- -b, --browser launch browser
- -h, --help help
-----
[3/5] isis git commit: ISIS-1521: moved a section on JDO mappings
from the fundamentals guide to the DN guide
Posted by da...@apache.org.
ISIS-1521: moved a section on JDO mappings from the fundamentals guide to the DN guide
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/ed24fc35
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/ed24fc35
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/ed24fc35
Branch: refs/heads/master
Commit: ed24fc35acab86c288e61c2768d26ea11374b50a
Parents: d0edbd4
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Fri Mar 24 07:10:34 2017 +0000
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Fri Mar 24 07:10:34 2017 +0000
----------------------------------------------------------------------
.../asciidoc/guides/_ugfun_jdo-mappings.adoc | 10 -
...ings_1-to-m-bidirectional-relationships.adoc | 321 -------------------
.../asciidoc/guides/_ugodn_jdo-mappings.adoc | 10 +
...ings_1-to-m-bidirectional-relationships.adoc | 321 +++++++++++++++++++
.../src/main/asciidoc/guides/ugfun.adoc | 1 -
.../src/main/asciidoc/guides/ugodn.adoc | 1 +
6 files changed, 332 insertions(+), 332 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/ed24fc35/adocs/documentation/src/main/asciidoc/guides/_ugfun_jdo-mappings.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_jdo-mappings.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_jdo-mappings.adoc
deleted file mode 100644
index 29eda2f..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_jdo-mappings.adoc
+++ /dev/null
@@ -1,10 +0,0 @@
-[[_ugfun_jdo-mappings]]
-= JDO Mappings
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-
-include::_ugfun_jdo-mappings_1-to-m-bidirectional-relationships.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/ed24fc35/adocs/documentation/src/main/asciidoc/guides/_ugfun_jdo-mappings_1-to-m-bidirectional-relationships.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_jdo-mappings_1-to-m-bidirectional-relationships.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_jdo-mappings_1-to-m-bidirectional-relationships.adoc
deleted file mode 100644
index 0623e67..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_jdo-mappings_1-to-m-bidirectional-relationships.adoc
+++ /dev/null
@@ -1,321 +0,0 @@
-[[_ugfun_jdo-mappings_1-to-m-bidirectional-relationships]]
-= 1-m Bidirectional relationships
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the 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/
-
-
-
-Consider a bidirectional one-to-many association between two entities; a collection member in the "parent" and a property member on the "child".
-
-We can tell DataNucleus about the bidirectionality using `@Persistent(mappedBy=...)`, or we can take responsibility for
-this aspect ourselves.
-
-In addition, the two entities can be associated either without or with a join table (indicated by the `@Join` annotation):
-
-* without a join table is more common; a regular foreign key in the child table for `FermentationVessel` points back up to the associated parent `Batch`
-* with a join table; a link table holds the tuple representing the linkage.
-
-Testing (as of `1.13.0`, against `dn-core 4.1.7`/`dn-rdbms 4.1.9`) has determined there are two main rules:
-
-* If not using `@Join`, then the association must be maintained by setting the child association on the parent. +
-+
-It is not sufficient to simply add the child object to the parent's collection.
-
-* `@Persistent(mappedBy=...)` and `@Join` cannot be used together. +
-+
-Put another way, if using `@Join` then you must maintain both sides of the relationship in the application code.
-
-
-In the examples that follow, we use two entities, `Batch` and `FermentationVessel` (from a brewery domain). In the
-original example domain the relationship between these two entities was optional (a `FermentationVessel` may
-have either none or one `Batch` associated with it); for the purpose of this article we'll explore both mandatory and
-optional associations.
-
-== Mandatory, no `@Join`
-
-In the first scenario we have use `@Persistent(mappedBy=...)` to indicate a bidirectional association, without any `@Join`:
-
-[source,java]
-----
-public class Batch {
-
- // getters and setters omitted
-
- @Persistent(mappedBy = "batch", dependentElement = "false") // <1>
- private SortedSet<FermentationVessel> vessels = new TreeSet<FermentationVessel>();
-}
-----
-<1> "mappedBy" means this is bidirectional
-
-and
-
-[source,java]
-----
-public class FermentationVessel implements Comparable<FermentationVessel> {
-
- // getters and setters omitted
-
- @Column(allowsNull = "false") // <1>
- private Batch batch;
-
- @Column(allowsNull = "false")
- private State state; // <2>
-}
-----
-<1> mandatory association up to parent
-<2> State is an enum (omitted)
-
-
-Which creates this schema:
-
-[source,sql]
-----
-CREATE TABLE "batch"."Batch"
-(
- "id" BIGINT GENERATED BY DEFAULT AS IDENTITY,
- ...
- "version" BIGINT NOT NULL,
- CONSTRAINT "Batch_PK" PRIMARY KEY ("id")
-)
-CREATE TABLE "fvessel"."FermentationVessel"
-(
- "id" BIGINT GENERATED BY DEFAULT AS IDENTITY,
- "batch_id_OID" BIGINT NOT NULL,
- "state" NVARCHAR(255) NOT NULL,
- ...
- "version" TIMESTAMP NOT NULL,
- CONSTRAINT "FermentationVessel_PK" PRIMARY KEY ("id")
-)
-----
-
-That is, there is an mandatory foreign key from `FermentationVessel` to `Batch`.
-
-
-In this case we can use this code:
-
-[source,java]
-----
-public Batch transfer(final FermentationVessel vessel) {
- vessel.setBatch(this); // <1>
- vessel.setState(FermentationVessel.State.FERMENTING);
- return this;
-}
-----
-<1> set the parent on the child
-
-This sets up the association correctly, using this SQL:
-
-[source,sql]
-----
-UPDATE "fvessel"."FermentationVessel"
- SET "batch_id_OID"=\<0>
- ,"state"=<'FERMENTING'>
- ,"version"=<2016-07-07 12:37:14.968>
- WHERE "id"=\<0>
-----
-
-
-The following code will also work:
-
-[source,java]
-----
-public Batch transfer(final FermentationVessel vessel) {
- vessel.setBatch(this); // <1>
- getVessels().add(vessel); // <2>
- vessel.setState(FermentationVessel.State.FERMENTING);
- return this;
-}
-----
-<1> set the parent on the child
-<2> add the child to the parent's collection.
-
-However, obviously the second statement is redundant.
-
-
-== Optional, no `@Join`
-
-If the association to the parent is made optional:
-
-[source,java]
-----
-public class FermentationVessel implements Comparable<FermentationVessel> {
-
- // getters and setters omitted
-
- @Column(allowsNull = "true") // <1>
- private Batch batch;
-
- @Column(allowsNull = "false")
- private State state;
-}
-----
-<1> optional association up to parent
-
-
-Which creates this schema:
-
-[source,sql]
-----
-CREATE TABLE "batch"."Batch"
-(
- "id" BIGINT GENERATED BY DEFAULT AS IDENTITY,
- ...
- "version" BIGINT NOT NULL,
- CONSTRAINT "Batch_PK" PRIMARY KEY ("id")
-)
-CREATE TABLE "fvessel"."FermentationVessel"
-(
- "id" BIGINT GENERATED BY DEFAULT AS IDENTITY,
- "batch_id_OID" BIGINT NULL,
- "state" NVARCHAR(255) NOT NULL,
- ...
- "version" TIMESTAMP NOT NULL,
- CONSTRAINT "FermentationVessel_PK" PRIMARY KEY ("id")
-)
-----
-
-This is almost exactly the same, except the foreign key from `FermentationVessel` to `Batch` is now nullable.
-
-
-In this case then setting the parent on the child still works:
-
-[source,java]
-----
-public Batch transfer(final FermentationVessel vessel) {
- vessel.setBatch(this); // <1>
- vessel.setState(FermentationVessel.State.FERMENTING);
- return this;
-}
-----
-<1> set the parent on the child
-
-*HOWEVER*, if we (redundantly) update both sides, then - paradoxically - the association is NOT set up
-
-[source,java]
-----
-public Batch transfer(final FermentationVessel vessel) {
- vessel.setBatch(this); // <1>
- getVessels().add(vessel); // <2>
- vessel.setState(FermentationVessel.State.FERMENTING);
- return this;
-}
-----
-<1> set the parent on the child
-<2> add the child to the parent's collection.
-
-[NOTE]
-====
-It's not clear if this is a bug in `dn-core 4.1.7`/`dn-rdbms 4.19`; an earlier thread on the mailing list from 2014 actually gave
-the opposite advice, see http://isis.markmail.org/thread/ipu2lzqqikqdglox[this thread] and in particular this http://markmail.org/message/hblptpw675mlw723[message].
-
-In fact we also have http://markmail.org/message/agnwmzocvdfht32f[a different case] which argues that the parent
-should only be set on the child, and the child _not_ added to the parent's collection. This concurs with the most recent testing.
-====
-
-Therefore, the simple advice is that, for bidirectional associations, simply set the parent on the child, and this will work
-reliably irrespective of whether the association is mandatory or optional.
-
-
-== With `@Join`
-
-Although DataNucleus does not complain if `@Persistence(mappedBy=...)` and `@Join` are combined, testing (against `dn-core 4.1.7`/`dn-rdbms 4.19`) has shown that the bidirectional association is not properly maintained.
-
-Therefore, we recommend that if `@Join` is used, then manually maintain both sides of the relationship and do not indicate
-that the association is bidirectional.
-
-For example:
-
-[source,java]
-----
-public class Batch {
-
- // getters and setters omitted
-
- @Join(table = "Batch_vessels")
- @Persistent(dependentElement = "false")
- private SortedSet<FermentationVessel> vessels = new TreeSet<FermentationVessel>();
-}
-----
-
-and
-
-[source,java]
-----
-public class FermentationVessel implements Comparable<FermentationVessel> {
-
- // getters and setters omitted
-
- @Column(allowsNull = "true") // <1>
- private Batch batch;
-
- @Column(allowsNull = "false")
- private State state;
-}
-----
-<1> optional association up to parent
-
-
-creates this schema:
-
-[source,sql]
-----
-CREATE TABLE "batch"."Batch"
-(
- "id" BIGINT GENERATED BY DEFAULT AS IDENTITY,
- ...
- "version" BIGINT NOT NULL,
- CONSTRAINT "Batch_PK" PRIMARY KEY ("id")
-)
-CREATE TABLE "fvessel"."FermentationVessel"
-(
- "id" BIGINT GENERATED BY DEFAULT AS IDENTITY,
- "state" NVARCHAR(255) NOT NULL,
- ...
- "version" TIMESTAMP NOT NULL,
- CONSTRAINT "FermentationVessel_PK" PRIMARY KEY ("id")
-)
-CREATE TABLE "batch"."Batch_vessels"
-(
- "id_OID" BIGINT NOT NULL,
- "id_EID" BIGINT NOT NULL,
- CONSTRAINT "Batch_vessels_PK" PRIMARY KEY ("id_OID","id_EID")
-)
-----
-
-That is, there is NO foreign key from `FermentationVessel` to `Batch`, instead the `Batch_vessels` table links the two together.
-
-
-These should then be maintained using:
-
-[source,java]
-----
-public Batch transfer(final FermentationVessel vessel) {
- vessel.setBatch(this); // <1>
- getVessels().add(vessel); // <2>
- vessel.setState(FermentationVessel.State.FERMENTING);
- return this;
-}
-----
-<1> set the parent on the child
-<2> add the child to the parent's collection.
-
-
-that is, explicitly update both sides of the relationship.
-
-This generates this SQL:
-
-[source,sql]
-----
-INSERT INTO "batch"."Batch_vessels" ("id_OID","id_EID") VALUES (<0>,<0>)
-UPDATE "batch"."Batch"
- SET "version"=\<3>
- WHERE "id"=\<0>
-UPDATE "fvessel"."FermentationVessel"
- SET "state"=<'FERMENTING'>
- ,"version"=<2016-07-07 12:49:21.49>
- WHERE "id"=\<0>
-----
-
-
-It doesn't matter in these cases whether the association is mandatory or optional; it will be the same SQL generated.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/ed24fc35/adocs/documentation/src/main/asciidoc/guides/_ugodn_jdo-mappings.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugodn_jdo-mappings.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugodn_jdo-mappings.adoc
new file mode 100644
index 0000000..908bb6f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugodn_jdo-mappings.adoc
@@ -0,0 +1,10 @@
+[[_ugodn_jdo-mappings]]
+= JDO Mappings
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+
+include::_ugodn_jdo-mappings_1-to-m-bidirectional-relationships.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/ed24fc35/adocs/documentation/src/main/asciidoc/guides/_ugodn_jdo-mappings_1-to-m-bidirectional-relationships.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugodn_jdo-mappings_1-to-m-bidirectional-relationships.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugodn_jdo-mappings_1-to-m-bidirectional-relationships.adoc
new file mode 100644
index 0000000..6c7ab01
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugodn_jdo-mappings_1-to-m-bidirectional-relationships.adoc
@@ -0,0 +1,321 @@
+[[_ugodn_jdo-mappings_1-to-m-bidirectional-relationships]]
+= 1-m Bidirectional relationships
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the 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/
+
+
+
+Consider a bidirectional one-to-many association between two entities; a collection member in the "parent" and a property member on the "child".
+
+We can tell DataNucleus about the bidirectionality using `@Persistent(mappedBy=...)`, or we can take responsibility for
+this aspect ourselves.
+
+In addition, the two entities can be associated either without or with a join table (indicated by the `@Join` annotation):
+
+* without a join table is more common; a regular foreign key in the child table for `FermentationVessel` points back up to the associated parent `Batch`
+* with a join table; a link table holds the tuple representing the linkage.
+
+Testing (as of `1.13.0`, against `dn-core 4.1.7`/`dn-rdbms 4.1.9`) has determined there are two main rules:
+
+* If not using `@Join`, then the association must be maintained by setting the child association on the parent. +
++
+It is not sufficient to simply add the child object to the parent's collection.
+
+* `@Persistent(mappedBy=...)` and `@Join` cannot be used together. +
++
+Put another way, if using `@Join` then you must maintain both sides of the relationship in the application code.
+
+
+In the examples that follow, we use two entities, `Batch` and `FermentationVessel` (from a brewery domain). In the
+original example domain the relationship between these two entities was optional (a `FermentationVessel` may
+have either none or one `Batch` associated with it); for the purpose of this article we'll explore both mandatory and
+optional associations.
+
+== Mandatory, no `@Join`
+
+In the first scenario we have use `@Persistent(mappedBy=...)` to indicate a bidirectional association, without any `@Join`:
+
+[source,java]
+----
+public class Batch {
+
+ // getters and setters omitted
+
+ @Persistent(mappedBy = "batch", dependentElement = "false") // <1>
+ private SortedSet<FermentationVessel> vessels = new TreeSet<FermentationVessel>();
+}
+----
+<1> "mappedBy" means this is bidirectional
+
+and
+
+[source,java]
+----
+public class FermentationVessel implements Comparable<FermentationVessel> {
+
+ // getters and setters omitted
+
+ @Column(allowsNull = "false") // <1>
+ private Batch batch;
+
+ @Column(allowsNull = "false")
+ private State state; // <2>
+}
+----
+<1> mandatory association up to parent
+<2> State is an enum (omitted)
+
+
+Which creates this schema:
+
+[source,sql]
+----
+CREATE TABLE "batch"."Batch"
+(
+ "id" BIGINT GENERATED BY DEFAULT AS IDENTITY,
+ ...
+ "version" BIGINT NOT NULL,
+ CONSTRAINT "Batch_PK" PRIMARY KEY ("id")
+)
+CREATE TABLE "fvessel"."FermentationVessel"
+(
+ "id" BIGINT GENERATED BY DEFAULT AS IDENTITY,
+ "batch_id_OID" BIGINT NOT NULL,
+ "state" NVARCHAR(255) NOT NULL,
+ ...
+ "version" TIMESTAMP NOT NULL,
+ CONSTRAINT "FermentationVessel_PK" PRIMARY KEY ("id")
+)
+----
+
+That is, there is an mandatory foreign key from `FermentationVessel` to `Batch`.
+
+
+In this case we can use this code:
+
+[source,java]
+----
+public Batch transfer(final FermentationVessel vessel) {
+ vessel.setBatch(this); // <1>
+ vessel.setState(FermentationVessel.State.FERMENTING);
+ return this;
+}
+----
+<1> set the parent on the child
+
+This sets up the association correctly, using this SQL:
+
+[source,sql]
+----
+UPDATE "fvessel"."FermentationVessel"
+ SET "batch_id_OID"=\<0>
+ ,"state"=<'FERMENTING'>
+ ,"version"=<2016-07-07 12:37:14.968>
+ WHERE "id"=\<0>
+----
+
+
+The following code will also work:
+
+[source,java]
+----
+public Batch transfer(final FermentationVessel vessel) {
+ vessel.setBatch(this); // <1>
+ getVessels().add(vessel); // <2>
+ vessel.setState(FermentationVessel.State.FERMENTING);
+ return this;
+}
+----
+<1> set the parent on the child
+<2> add the child to the parent's collection.
+
+However, obviously the second statement is redundant.
+
+
+== Optional, no `@Join`
+
+If the association to the parent is made optional:
+
+[source,java]
+----
+public class FermentationVessel implements Comparable<FermentationVessel> {
+
+ // getters and setters omitted
+
+ @Column(allowsNull = "true") // <1>
+ private Batch batch;
+
+ @Column(allowsNull = "false")
+ private State state;
+}
+----
+<1> optional association up to parent
+
+
+Which creates this schema:
+
+[source,sql]
+----
+CREATE TABLE "batch"."Batch"
+(
+ "id" BIGINT GENERATED BY DEFAULT AS IDENTITY,
+ ...
+ "version" BIGINT NOT NULL,
+ CONSTRAINT "Batch_PK" PRIMARY KEY ("id")
+)
+CREATE TABLE "fvessel"."FermentationVessel"
+(
+ "id" BIGINT GENERATED BY DEFAULT AS IDENTITY,
+ "batch_id_OID" BIGINT NULL,
+ "state" NVARCHAR(255) NOT NULL,
+ ...
+ "version" TIMESTAMP NOT NULL,
+ CONSTRAINT "FermentationVessel_PK" PRIMARY KEY ("id")
+)
+----
+
+This is almost exactly the same, except the foreign key from `FermentationVessel` to `Batch` is now nullable.
+
+
+In this case then setting the parent on the child still works:
+
+[source,java]
+----
+public Batch transfer(final FermentationVessel vessel) {
+ vessel.setBatch(this); // <1>
+ vessel.setState(FermentationVessel.State.FERMENTING);
+ return this;
+}
+----
+<1> set the parent on the child
+
+*HOWEVER*, if we (redundantly) update both sides, then - paradoxically - the association is NOT set up
+
+[source,java]
+----
+public Batch transfer(final FermentationVessel vessel) {
+ vessel.setBatch(this); // <1>
+ getVessels().add(vessel); // <2>
+ vessel.setState(FermentationVessel.State.FERMENTING);
+ return this;
+}
+----
+<1> set the parent on the child
+<2> add the child to the parent's collection.
+
+[NOTE]
+====
+It's not clear if this is a bug in `dn-core 4.1.7`/`dn-rdbms 4.19`; an earlier thread on the mailing list from 2014 actually gave
+the opposite advice, see http://isis.markmail.org/thread/ipu2lzqqikqdglox[this thread] and in particular this http://markmail.org/message/hblptpw675mlw723[message].
+
+In fact we also have http://markmail.org/message/agnwmzocvdfht32f[a different case] which argues that the parent
+should only be set on the child, and the child _not_ added to the parent's collection. This concurs with the most recent testing.
+====
+
+Therefore, the simple advice is that, for bidirectional associations, simply set the parent on the child, and this will work
+reliably irrespective of whether the association is mandatory or optional.
+
+
+== With `@Join`
+
+Although DataNucleus does not complain if `@Persistence(mappedBy=...)` and `@Join` are combined, testing (against `dn-core 4.1.7`/`dn-rdbms 4.19`) has shown that the bidirectional association is not properly maintained.
+
+Therefore, we recommend that if `@Join` is used, then manually maintain both sides of the relationship and do not indicate
+that the association is bidirectional.
+
+For example:
+
+[source,java]
+----
+public class Batch {
+
+ // getters and setters omitted
+
+ @Join(table = "Batch_vessels")
+ @Persistent(dependentElement = "false")
+ private SortedSet<FermentationVessel> vessels = new TreeSet<FermentationVessel>();
+}
+----
+
+and
+
+[source,java]
+----
+public class FermentationVessel implements Comparable<FermentationVessel> {
+
+ // getters and setters omitted
+
+ @Column(allowsNull = "true") // <1>
+ private Batch batch;
+
+ @Column(allowsNull = "false")
+ private State state;
+}
+----
+<1> optional association up to parent
+
+
+creates this schema:
+
+[source,sql]
+----
+CREATE TABLE "batch"."Batch"
+(
+ "id" BIGINT GENERATED BY DEFAULT AS IDENTITY,
+ ...
+ "version" BIGINT NOT NULL,
+ CONSTRAINT "Batch_PK" PRIMARY KEY ("id")
+)
+CREATE TABLE "fvessel"."FermentationVessel"
+(
+ "id" BIGINT GENERATED BY DEFAULT AS IDENTITY,
+ "state" NVARCHAR(255) NOT NULL,
+ ...
+ "version" TIMESTAMP NOT NULL,
+ CONSTRAINT "FermentationVessel_PK" PRIMARY KEY ("id")
+)
+CREATE TABLE "batch"."Batch_vessels"
+(
+ "id_OID" BIGINT NOT NULL,
+ "id_EID" BIGINT NOT NULL,
+ CONSTRAINT "Batch_vessels_PK" PRIMARY KEY ("id_OID","id_EID")
+)
+----
+
+That is, there is NO foreign key from `FermentationVessel` to `Batch`, instead the `Batch_vessels` table links the two together.
+
+
+These should then be maintained using:
+
+[source,java]
+----
+public Batch transfer(final FermentationVessel vessel) {
+ vessel.setBatch(this); // <1>
+ getVessels().add(vessel); // <2>
+ vessel.setState(FermentationVessel.State.FERMENTING);
+ return this;
+}
+----
+<1> set the parent on the child
+<2> add the child to the parent's collection.
+
+
+that is, explicitly update both sides of the relationship.
+
+This generates this SQL:
+
+[source,sql]
+----
+INSERT INTO "batch"."Batch_vessels" ("id_OID","id_EID") VALUES (<0>,<0>)
+UPDATE "batch"."Batch"
+ SET "version"=\<3>
+ WHERE "id"=\<0>
+UPDATE "fvessel"."FermentationVessel"
+ SET "state"=<'FERMENTING'>
+ ,"version"=<2016-07-07 12:49:21.49>
+ WHERE "id"=\<0>
+----
+
+
+It doesn't matter in these cases whether the association is mandatory or optional; it will be the same SQL generated.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/ed24fc35/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
index c5c771e..0a7ae0a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun.adoc
@@ -51,7 +51,6 @@ include::_ugfun_core-concepts.adoc[leveloffset=+1]
include::_ugfun_getting-started.adoc[leveloffset=+1]
include::_ugfun_how-tos.adoc[leveloffset=+1]
-include::_ugfun_jdo-mappings.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/ed24fc35/adocs/documentation/src/main/asciidoc/guides/ugodn.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn.adoc
index 1a9c6a8..d28b169 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugodn.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugodn.adoc
@@ -59,6 +59,7 @@ for Apache Isis and contribute back to the project)
include::_ugodn_configuring.adoc[leveloffset=+1]
+include::_ugodn_jdo-mappings.adoc[leveloffset=+1]
include::_ugodn_overriding-jdo-annotations.adoc[leveloffset=+1]
include::_ugodn_java8.adoc[leveloffset=+1]