Merge branch 'master' of https://github.com/ogcincubator/bblocks-docs

# Conflicts:
#	_data/navigation.yml
#	_pages/index.markdown

Author: rob-metalinkage

_data/navigation.yml

@@ -11,15 +11,18 @@ docs:
         url: /overview/types 
       - title: Types (Patterns)
         url: /overview/types#patterns
-        
+  - title: Quick Start
+    children:
+      - title: Local Build
+        url: /build/local
   - title: Using the Building Blocks
     children:
       - title: Finding Building Blocks
         url: /use/finding
       - title: Reusing schemas
-      - title: Reusing schemas
-        url: /use/ftc
+        url: /use/reusing-schemas
       - title: Linked Data / JSON-LD Context
+        url: /use/linked-data
   - title: Creating Building Blocks
     children:
       - title: Overview

_pages/build/local.md

@@ -0,0 +1,27 @@
+---
+title: Quick Start - local build
+permalink: /build/local
+---
+
+
+## Quick how-to create
+
+1. Install docker
+2. Check out any valid Building Block implementation (e.g. [bblocks-examples](https://ogcincubator.github.io/bblocks-examples/))
+3. cd to the new directory
+4. run build.sh or build.bat if present
+   - this will access the current build scripts and compile the building block locally
+   - if not present run the command 
+ ```shell
+# Process building blocks
+docker run --pull=always --rm --workdir /workspace -v "$(pwd):/workspace" \
+  ghcr.io/opengeospatial/bblocks-postprocess  --clean true
+```
+5. run the view.sh or view.bat to preview the local build
+ - if not present run 
+ ```shell
+docker run --rm --pull=always -v "$(pwd):/register" -p 9090:9090 ghcr.io/ogcincubator/bblocks-viewer
+```
+You can now experiment with the source material - or proceed to [create your own building blocks](../create).
+
+(create a fork if you want to update the the repository so you can submit pull requests. The local build outputs will be ignored automatically on updates.)

_pages/create/index.md

@@ -2,13 +2,15 @@
 title: How to create Building Blocks
 permalink: /create
 ---
-Building Blocks can be reused by either:
+## starting point options:
 
-- cut and paste "ready to use" forms from the `build/` directory
-- directly reference the artefacts in the `build` directory using the URL pattern specified in the building block
-  description
+1. Create from scratch using a template - see below
+2. Fork an existing repository to update or add new building blocks, and generate a Pull Request to submit to the register owner
+2. Copy any building block repository and edit `bblocks-config.yaml` and the `_sources/*` to create a new register
 
-## Quick how-to
+In all cases follow the [local build process](../build/local) to test before committing to an online repository.
+
+## Quick how-to create
 
 1. Navigate to the [bblock-template](https://github.com/opengeospatial/bblock-template) repository.
 2. Click on "Use this template" on GitHub (do not fork this repository, or you will have to manually enable the

_pages/create/metadata.md

@@ -4,4 +4,4 @@ permalink: /create/metadata
 ---
 Building block metadata provides context information about the item in the building blocks register. It is based on [ISO 19135](https://www.iso.org/standard/54721.html), the standard for item registration of geographic information, from which it extracted its six mandatory items (flagged with *). The ISO schema is extended with other properties (in green), which account for things such as the visual representation in the register, item validation or relation with other building blocks.
 
-[![building block](/assets/bblock.png)](/assets/bblock.png)
+[![building block](../assets/bblock.png)](../assets/bblock.png)

_pages/create/rdf-only.md

@@ -5,8 +5,8 @@ permalink: /create/rdf-only
 Building Blocks can be defined that use RDF only. An RDF building block can:
 
 1. Define RDF (TTL) examples how to use the Semantic model
-2. Apply SHACL Rules to [validate examples](TESTING.md#SHACL)
-3. [Perform transforms](TXFORMS.md) and validate results
+2. Apply SHACL Rules to [validate examples](validation#shacl-validation)
+3. [Perform transforms](transforms) and validate results
 
 Test cases and examples as either TTL or JSONLD will undergo syntax and SHACL validation.
 

_pages/create/schema.md

@@ -39,7 +39,7 @@ this is done in a two-step process:
 
 2. use the `bblocks:://{id}` syntax as href in schema $ref elements. 
 
-    This means your building block will inherit all json-ld contexts and SHACL rules from the referenced building block automatically and apply during [testing](TESTING.md).
+    This means your building block will inherit all json-ld contexts and SHACL rules from the referenced building block automatically and apply during [testing](../create/validation).
 
 
 # Profiling JSON Schemas

_pages/create/structure.md

@@ -5,7 +5,7 @@ permalink: /create/structure
 
 The following image summarizes the general usage of a building block:
 
-[![Usage](/assets/usage.png)](/assets/usage.png)
+[![Usage](../assets/usage.png)](../assets/usage.png)
 
 ## Building Block sources
 

_pages/index.markdown

@@ -4,11 +4,13 @@ permalink: /
 ---
 This is the documentation for OGC Building Blocks, a specification component packaging approach that can be used to **add documentation** to existing specification components, or to assemble specifications cost-effectively using a test-driven approach.
 
-This packaging supports testing of examples, and validation using rules inherited from other Building Blocks that are re-used (by aggregation or profiling) to create compatible specifications for specific applications.
+![](../assets/bblocks-qr.png)
+
+Building Blocks may be various [types](overview/types) - however the emphasis is semantically annotated schemas for use in OGC API definitions. 
 
-Building Blocks make various different [types](/overview/types) of specification component accessible in a common, convenient form and registers.  A key innovation is support for **semantically annotated schemas**, suitable for use in OpenAPI definitions. 
+A key application is the [register of OGC Specification Building blocks](https://opengeospatial.github.io/bblocks/register/)
 
-The Building Block documentation framework is the basis of the [register of OGC Specification Building blocks](https://opengeospatial.github.io/bblocks/register/). 
+This packaging supports testing of examples, and validation using rules inherited from other Building Blocks that are re-used (by aggregation or profiling) to create compatible specifications for specific applications.
 
-OGC BuildingBlocks can be organised into [registers](/overview/registers) for convenience, each repository creating a local register that can be aggregated into another application domain register.
+OGC BuildingBlocks can be organised into [registers](overview/registers) for convenience, each repository creating a local register that can be aggregated into another application domain register.
 

_pages/overview/profiles.md

@@ -28,6 +28,17 @@ Because many technologies like JSON and RDF are permissive (by default) about ad
 Profiles can be designed as separate re-usable sets of constraints that can be reused - for example a time-series of water-quality monitoring observations could be specified as a profile of both a time-series profile of Observations and a water-quality profile for the results of such observations.
 In turn the time-series profile could defined as data structure using GeoJSON, or Coverage JSON.  The water-quality content requirements could be described using constraints independent of the data structure.
 
+## Profiles for infrastructure compatibility
+
+Profiles can be layered to meet different needs. The typical usage is for applications that are compatible with shared infrastructures, where applications may be designed to interact with other applications, but the supporting infrastructures for these applications may also be designed to interoperate with other infrastructures.
+
+Underlying standards allow reusable software and libraries to be used at all levels.
+
+This can be visualised as a layered model of typical profiles, identifying the types of constraints typically present at each layer. 
+
+![Profile layers](profiles.png)
+
+
 ## What forms of constraints are possible?
 
 The **OGC BuildingBlock** model supports a range of possible constraint approaches.  The goal is to make such constraints **_machine-readable_** to the extent possible.
@@ -40,7 +51,7 @@ Built-in support is provided for automatic validation of the following forms:
 - JSON schema (for JSON examples) for **structure**
 - SHACL (Shapes Constraint Language for RDF) for **content** and **logical consistency**
 
-In addition [custom validators](VALIDATORS) can be added to the validation workflow. 
+In addition [custom validators](../create/validation) can be added to the validation workflow. 
 
 Using a JSON-LD context "semantic uplift" of JSON to RDF supports use of SHACL and other forms of validators to 
 

_pages/overview/profiles.png

@@ -8,7 +8,7 @@ Whilst components described as Building Blocks may be referenced by individual s
 
 The OGC Building Block Framework provides three improved approaches for discovery:
 
-1. [Registers](/overview/registers)
+1. [Registers](../overview/registers)
 1. [RAINBOW (OGC Knowledge Graph)]() 
 1. Transparent Dependencies 
 

_pages/use/finding.md

@@ -0,0 +1,6 @@
+---
+title: Linked Data / JSON-LD Context
+permalink: /use/linked-data
+---
+
+# TBD

_pages/use/linked-data.md

@@ -0,0 +1,12 @@
+---
+title: Reusing schemas
+permalink: /use/reusing-schemas
+---
+
+Building Blocks can be reused in several ways:
+
+- if creating a JSON schema based BuildingBlock then use the $ref: bblocks://{block id} to make a JSON schema reference to any building block in the import list [see imports](../create/imports)
+- for other [types of Building Blocks](../overview/types) declare as an entry in the dependsOn element of a `block.json` metadata file
+- cut and paste "ready to use" forms from the `build/` directory of any building block repository into a some other form of application (not a reusable Building Block itself)
+- directly reference the artefacts in the `build` directory using the URL pattern specified in the building block
+  description (noting this may be affected by changes if a building block is moved from one register to another - bblocks:// references will still work if imports approach is used.)