Documentation Upgrade (#182)

* Significant work done to get more concepts explained
* Make all the links in concepts use the relref shortcode
* Add a DCO notice
* Add the who-made-riddl-possible attribution page
* Add the idea of "Vital Definitions" and preview what
  some future version of RIDDL will support with this notion

DCO.text

@@ -0,0 +1,34 @@
+Developer Certificate of Origin
+Version 1.1
+
+Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
+
+Everyone is permitted to copy and distribute verbatim copies of this
+license document, but changing it is not allowed.
+
+
+Developer's Certificate of Origin 1.1
+
+By making a contribution to this project, I certify that:
+
+(a) The contribution was created in whole or in part by me and I
+    have the right to submit it under the open source license
+    indicated in the file; or
+
+(b) The contribution is based upon previous work that, to the best
+    of my knowledge, is covered under an appropriate open source
+    license and I have the right under that license to submit that
+    work with modifications, whether created in whole or in part
+    by me, under the same open source license (unless I am
+    permitted to submit under a different license), as indicated
+    in the file; or
+
+(c) The contribution was provided directly to me by some other
+    person who certified (a), (b) or (c) and I have not modified
+    it.
+
+(d) I understand and agree that this project and the contribution
+    are public and that a record of the contribution (including all
+    personal information I submit with it, including my sign-off) is
+    maintained indefinitely and may be redistributed consistent with
+    this project or the open source license(s) involved.

README.md

@@ -143,3 +143,17 @@ In `examples/src/test/scala` there is a `CheckExamplesSpec.scala` which runs
 the parser and validator on the examples in `examples/src/riddl`. Each 
 sub-directory there is a separate example. They are expected to parse and 
 validate cleanly without issue 
+
+### Contributing
+_Contributions are very welcome!_
+
+If you see an issue that you'd like to see fixed, or want us to consider a
+change, the best way to make it happen is to help out by submitting a 
+pull request implementing it. We welcome contributions from all, even if
+you are not yet familiar RIDDL. We will endeavour to guide you through the 
+process once you've submitted your PR. 
+
+Please refer to the CONTRIBUTING.md file for more details about the workflow, 
+and general hints on how to prepare your pull request. You can also ask for
+clarifications or guidance in GitHub issues directly
+

doc/src/hugo/content/concepts/_index.md

@@ -8,59 +8,117 @@ In this section we will explore the concepts and ideas that RIDDL uses. This is
 not about the RIDDL language or syntax, but about the concepts that the
 language uses and how they relate to each other.
 
+## Common Attributes
 
-## Concepts
-The concepts employed by RIDDL are arranged hierarchically. The sections
-of this documentation describing these concepts are similarly arranged 
-hierarchically. It is suggested that you read in the order suggested here
-(depth first):
+Everything you can define in RIDDL is a definition. All definitions share common
+attributes:
 
-* [Root](root)
-  * [Domains](domain)
-    * [Options](option)
-    * [Authors](author)
-    * [Types](type)
-      * [Fields](field)
-    * [Contexts](context)
-      * [Options](option)
-      * [Types](type)
-      * [Entities](entity)
-        * [Options](option)
-        * [Types](type)
-        * [Functions](function)
-          * [Examples](example)
-            * [Actions](action)
-              * [Expressions](expression)
-        * [States](state)
-          * [Fields](field)
-        * [Invariants](invariant)
-        * [Handlers](handler)
-          * [On Clauses](onclause)
-            * [Examples](example)
-              * [Actions](action)
-                * [Expressions](expression)
-        * [Includes](include)
-      * [Handlers](handler)
-        * [On Clauses](onclause)
-          * [Examples](example)
-            * [Actions](action)
-              * [Expressions](expression)
-      * [Projections](projection)
-      * [Sagas](saga)
-      * [Adaptors](adaptor)
-        * [Adaptations](adaptation)
-      * [Processors](processor)
-      * [Functions](function)
-        * [Examples](example)
-          * [Actions](action)
-            * [Expressions](expression)
-      * [Terms](term)
-      * [Includes](include)
-    * [Stories](story)
-    * [Plants](plant)
-      * [Processors](processor)
-      * [Joints](joint)
-      * [Pipes](pipe)
-    * [Terms](term)
-    * [Includes](include)
+* _loc_: The location of the definition in its input file. (line & column)
+* _id_: The name, or identifier, of the definition. 
+* _briefly_: A string to briefly describe the definition. These are used in 
+  the documentation output and the glossary. 
+* _description_: A block of 
+   [Markdown](https://www.markdownguide.org/getting-started/) that 
+  fully describes the definition. All the facilities provided by the  
+  [hugo-geekdoc](https://geekdocs.de/) template for hugo are supported.
+
+These attributes merely provide supplemental information about the 
+definition but are not part of the definition.  
+
+## Attributes of Vital Definitions
+The [vital definitions]({{< relref "vital.md" >}}) share a set of 
+common attributes that, like the [Common Attributes](#common-attributes),
+are informational rather than definitional. 
+
+These are the common attributes that 
+[vital definitions]({{< relref "vital.md" >}}) share:
+* [_includes_]({{< relref "include.md" >}}) - include content from another file
+* [_options_]({{< relref "option.md" >}}) - define translation options for the
+  definition
+* [_authors_]({{< relref "author.md" >}}) - define who the authors of the
+  definition are
+* [_terms_]({{< relref "term.md" >}}) - define a term as part of the
+  ubiquitous language for the definition.
+
+## Definitional Hierarchy
+
+RIDDL uses a hierarchy of nested definitions as its primary structure. This 
+is done simply by having an attribute that lists the contents of any 
+definition:
+
+* _contents_: The contained definitions that define the container. Not all 
+  definitions can contain other ones so sometimes this is empty.
+
+Consequently, a hierarchical structure is used below as well. However, to 
+make this hierarchy shorter and easier to comprehend, we've taken some 
+short-cuts :
+
+1. All the common attributes and the Vital Definition attributes 
+are not shown in the hierarchy but implied by the above sections.
+2. We only descend as far as an [Example]({{< relref "example.md" >}}) 
+   definition. Whenever you see one, you should infer this hierarchy:
+  * [Examples]({{< relref "example.md" >}})
+    * [Actions]({{< relref "action.md" >}})
+      * [Expressions]({{< relref "expression.md" >}})
+3. We only descend as far as a [Type]({{< relref "type.md" >}}) definition. 
+   Whenever you see one, you should infer this hierarchy: 
+  * [Types]({{< relref "type.md" >}})
+    * [Fields]({{< relref "field.md" >}})
+
+With those clarifying simplifications, here's the hierarchy:
+* [Root]({{< relref "root.md" >}})
+  * [Domains]({{< relref "domain.md" >}})
+    * [Types]({{< relref "type.md" >}})
+    * [Contexts]({{< relref "context.md" >}})
+      * [Types]({{< relref "type.md" >}})
+      * [Entities]({{< relref "entity.md" >}})
+        * [Types]({{< relref "type.md" >}})
+        * [Functions]({{< relref "function.md" >}})
+          * [Examples]({{< relref "example.md" >}})
+        * [States]({{< relref "state.md" >}})
+          * [Types]({{< relref "type.md" >}})
+          * [Fields]({{< relref "field.md" >}})
+          * [Handlers]({{< relref "handler.md" >}})
+            * [On Clauses]({{< relref "onclause.md" >}})
+              * [Examples]({{< relref "example.md" >}})
+        * [Invariants]({{< relref "invariant.md" >}})
+          * [Expressions]({{< relref "expression.md" >}})
+        * [Handlers]({{< relref "handler.md" >}})
+          * [On Clauses]({{< relref "onclause.md" >}})
+            * [Examples]({{< relref "example.md" >}})
+      * [Handlers]({{< relref "handler.md" >}})
+        * [On Clauses]({{< relref "onclause.md" >}})
+          * [Examples]({{< relref "example.md" >}})
+      * [Projections]({{< relref "projection.md" >}})
+        * [Types]({{< relref "type.md" >}})
+        * [Fields]({{< relref "field.md" >}})
+        * [Handlers]({{< relref "handler.md" >}})
+          * [On Clauses]({{< relref "onclause.md" >}})
+            * [Examples]({{< relref "example.md" >}})
+      * [Sagas]({{< relref "saga.md" >}})
+        * [Types]({{< relref "type.md" >}})
+        * [SagaStep]({{< relref "sagastep.md" >}})
+          * [Examples]({{< relref "example.md" >}})
+      * [Adaptors]({{< relref "adaptor.md" >}})
+        * [Types]({{< relref "type.md" >}})
+        * [Adaptations]({{< relref "adaptation.md" >}})
+          * [Examples]({{< relref "example.md" >}})
+      * [Processors]({{< relref "processor.md" >}})
+        * [Types]({{< relref "type.md" >}})
+        * [Inlet]({{< relref "inlet.md" >}}) 
+        * [Outlet]({{< relref "outlet.md" >}})
+        * [Examples]({{< relref "example.md" >}})
+      * [Functions]({{< relref "function.md" >}})
+        * [Examples]({{< relref "example.md" >}})
+    * [Stories]({{< relref "story.md" >}})
+      * [Examples]({{< relref "example.md" >}})
+    * [Plants]({{< relref "plant.md" >}})
+      * [Processors]({{< relref "processor.md" >}})
+        * [Types]({{< relref "type.md" >}})
+        * [Inlet]({{< relref "inlet.md" >}})
+        * [Outlet]({{< relref "outlet.md" >}})
+        * [Examples]({{< relref "example.md" >}})
+        * [InletJoints]({{< relref "joint.md" >}})
+        * [OutletJoints]({{< relref "joint.md" >}})
+        * [Pipes]({{< relref "pipe.md" >}})
 

doc/src/hugo/content/concepts/action.md

@@ -3,11 +3,63 @@ title: "Action"
 draft: false
 ---
 
-An Action is something a program does. 
+An Action is something a program does. Actions are used in the 
+[`then`]({{< relref "example.md#then" >}})
+and 
+[`but`]({{< relref "example.md#but" >}}) clauses of an 
+[example]({{< relref "example.md" >}}). 
+
+There are many kinds of Actions, described in the table below
+
+|     Name     | Description                                                  |
+|:------------:|:-------------------------------------------------------------|
+|    Append    | Add an item to a field that is a collection                  |
+|  Arbitrary   | A textually described arbitrary action                       |
+|     Ask      | Send a message to an entity, asynchronously process result   |
+|    Become    | Instructs an entity change to a new handler                  |
+|   Compound   | Execute a group of nested actions                            |
+|    Error     | Produce an error with a message                              |
+| FunctionCall | Call a function to get a result                              |
+|    Morph     | Morph the state of an entity to a new state                  |
+|   Publish    | Publish a message to a pipe                                  |
+|    Reply     | Provide the reply message to the entity that invoked a query |
+|    Return    | Return a value from a function                               |
+|     Set      | Set a field of the current state of an entity                |
+|     Tell     | Send a message to an entity, do not wait for result          |
+|    Yield     | Place a message on an entity's event pipe                    |
+
+## Applicability
+Not all actions can be used in every situation. The table below show the 
+exceptions. Examples occur in
+[handlers]({{< relref "handler.md" >}}) and they in turn occur in
+[contexts]({{< relref "context.md" >}}),
+[entities]({{< relref "entity.md" >}}),
+[functions]({{< relref "function.md" >}}),
+[projections]({{< relref "projection.md" >}}), and
+[states]({{< relref "state.md" >}}).
+
+
+|     Name     | Context | Entity | Function | Projection | State |
+|:------------:|:-------:|:------:|:--------:|:----------:|:-----:|
+|    Append    |    ⚠    |   ✓    |    ⚠     |     ✓      |   ✓   |
+|  Arbitrary   |    ✓    |   ✓    |    ✓     |     ✓      |   ✓   |
+|     Ask      |    ✓    |   ✓    |    ✓     |     ✓      |   ✓   |
+|    Become    |    ⚠    |   ✓    |    ⚠     |     ✓      |   ✓   |
+|   Compound   |    ✓    |   ✓    |    ✓     |     ✓      |   ✓   |
+|    Error     |    ✓    |   ✓    |    ✓     |     ✓      |   ✓   |
+| FunctionCall |    ✓    |   ✓    |    ✓     |     ✓      |   ✓   |
+|    Morph     |    ⚠    |   ✓    |    ⚠     |     ⚠      |   ✓   |
+|   Publish    |    ✓    |   ✓    |    ✓     |     ✓      |   ✓   |
+|    Reply     |    ⚠    |   ✓    |    ⚠     |     ✓      |   ✓   |
+|    Return    |    ✓    |   ⚠    |    ✓     |     ✓      |   ⚠   |
+|     Set      |    ⚠    |   ✓    |    ⚠     |     ✓      |   ✓   |
+|     Tell     |    ✓    |   ✓    |    ✓     |     ✓      |   ✓   |
+|    Yield     |    ⚠    |   ✓    |    ✓     |     ✓      |   ✓   |
+
 
 ## Occurs In
-* [Examples](example) - `then` and `but` clauses
+* [Examples]({{< relref "example.md" >}}) - in the `then` and `but` clauses
 
 
 ## Contains
-* [Expressions](expression)
+* [Expressions]({{< relref "expression.md" >}}) - to 

doc/src/hugo/content/concepts/adaptation.md

@@ -3,10 +3,21 @@ title: "Adaptation"
 draft: false
 ---
 
-TBD
+An adaptation is a single component of an 
+[adaptor]({{< relref "adaptor.md" >}}) that defines a specific kind of 
+translation or adaptation to undertake. There are several kinds of 
+adaptations that can be defined, all pertain to message handling. 
+
+|      Name      | Description                                               |
+|:--------------:|:----------------------------------------------------------|
+|  EventCommand  | Transformation of an incoming Event to a Command          |
+| CommandCommand | Transformation of an incoming Command to another Command  |
+|  EventAction   | Transformation of an incoming Event to a set of Actions   |
+| CommandAction  | Transformation of an incoming Command to a set of Actions |
+
 
 ## Occurs In
-* [Adaptors](adaptor)
+* [Adaptors]({{< relref "adaptor.md" >}})
 
 ## Contains
-* [Examples](example)
+* [Examples]({{< relref "example.md" >}})

doc/src/hugo/content/concepts/adaptor.md

@@ -3,10 +3,20 @@ title: "Adaptor"
 draft: false
 ---
 
-TBD
+An adaptor's purpose is to _adapt_ one [context]({{< relref "context.md" >}})
+to another. In Domain-Driven Design, this concept is known as an
+_anti-corruption layer_.  We didn't like that term for a variety of reasons 
+so we have renamed the concept as _adaptor_ in RIDDL. Same idea, different name.
+
+Adaptors simply bundle together a set of 
+[adaptations]({{< relref "adaptation.md" >}}). The actions they take are 
+aimed at the [context]({{< relref "context.md" >}}) that contains the 
+adaptor or any [entity]({{< relref "entity.md" >}}) or 
+[projection]({{< relref "projection.md" >}}) within that context. 
+
 
 ## Occurs In
-* [Contexts](context)
+* [Contexts]({{< relref "context.md" >}})
 
 ## Contains
-* [Adaptations](adaptation)
+* [Adaptations]({{< relref "adaptation.md" >}})

doc/src/hugo/content/concepts/author.md

@@ -1,17 +1,19 @@
 ---
-title: "AuthorInfo"
+title: "Author"
 draft: false
 ---
 
-An author definition merely describes one of the authors that wrote the defintion
-in which the author is defined. 
+An author definition merely describes one of the authors that wrote the 
+encapsulating definition. An author definition contains the usual profile 
+information for a human including:
+* full name
+* email address
+* name of an organization (optional)
+* title at that organization (optional)
+* url for more information (optional)
 
 ## Occurs In
-
-* [Domains](domain)
-* [Contexts](context)
-* [Entities](entity)
-* [Stories](story)
+All [vital definitions]({{< relref "vital.md" >}})
 
 ## Contains
 No other definitions