update the site

clean up some formatting errors
add a little more explanatory text about model import.

doc/guide/JavaCodeGeneration.md

@@ -98,7 +98,7 @@ At this point the overall model object is suitable to be serialized.
 On reading in a model instance, it is possible to extract any top level ObjectTypes
 with the `public <T> List<T> getContent(Class<T> c)` method.
 
-!!! Note "contained references"
+!!! note "contained references"
 
     There is some provisional support for "contained references" when cloning an object - the API for this 
     is subject to change, but an example is used in [copyTest](https://github.com/ivoa/vo-dml/blob/519f213830c0a946a0d63be65552067bfc707f1d/tools/gradletooling/sample/src/test/java/org/ivoa/dm/lifecycle/LifeCycleDetailedTest.java#L99C10-L99C18) using the `createContext()` and `updateClonedReferences()` methods either side of an object clone with a copy constructor.

doc/guide/QuickStart.md

@@ -10,14 +10,12 @@ If starting a completely new data model then the [Template DM Project](https://g
 If adapting an existing data model repository then
 
 1. Edit a `build.gradle.kts` file with reference to the plugin (note substitute ![latest published version](https://img.shields.io/gradle-plugin-portal/v/net.ivoa.vo-dml.vodmltools?label=latest%20published%20version) below)
-
 ```kotlin
 plugins {
     id("net.ivoa.vo-dml.vodmltools") version "0.x.x"
 }
 ```
 2. create a `settings.gradle.kts` - it is possible just to copy the [template version](https://github.com/ivoa/DataModelTemplate/blob/master/settings.gradle.kts) and just edit the `rootProject.name`.
-
 3. create the binding file for the model (see [below](#binding-files)) for more detail 
 
 There is nothing else that needs to be done if the VO-DML files in the default place 
@@ -32,10 +30,8 @@ gradle vodmlValidate
 ```
 will attempt to validate the model and print any errors.
 
-* vodmlValidate - runs validation on the models.
-*
-* vodmlJavaGenerate - generate java classes. See [generated code guide](JavaCodeGeneration.md) for details of how to use the generated java code to serialize instances to XML and RDB.
- Note that it is also possible to test models using the generated code.
+If the validation is successful you can produce [various derived products](Transformers.md). Developing your VO-DML model further is discussed [here](modelling/modellingIntro.md). 
+
 
 ## Detailed configuration
 
@@ -47,6 +43,8 @@ vodml {
 ```
 section in the `build.gradle.kts` file.
 
+The various sub-properties that can be set are
+
 * _vodmlDir_ - the default is `src/main/vo-dml`
   ```kotlin
   vodmlDir.set(file("vo-dml"))
@@ -59,6 +57,7 @@ section in the `build.gradle.kts` file.
 * _outputSiteDir_ - where the [mkdocs](https://www.mkdocs.org) suitable model description is created by the `gradle vodmlSite` command - default `build/generated/docs/vodml-site`.
 * _outputJavaDir_ - where the generated Java is created - the default is `build/generated/sources/vodml/java/` and it should not 
   be necessary to ever alter this as gradle will integrate this automatically into the various source paths.
+* _outputSchemaDir_ - where the XML and JSON schema are generated to - the default is `build/generated/sources/vodml/schema/` - this is automatically included in the classpath and the output jar.
 * _catalogFile_ - in general it is not necessary to set this, as the plugin will create a catalogue file automatically from the vodmlDir and vodmlFiles properties (as well as including files in any dependencies that also contain VO-DML models)
   A catalogue file is necessary as the rest of the tooling is designed to use only the filename (no path) for inclusions and references.
   If it is desired to create a file manually for a special purpose, then the file should have the format as below - it should be noted that all references to model files will have to be specified if this is done.

doc/guide/Transformers.md

@@ -33,3 +33,6 @@ gradle vodmlSchema
 ```
 will generate XML and JSON schema for the model. These schema files will automatically be included withing the jar file for the model.
 
+# Transformation to VO-DML
+
+The transformation of other data model representations to VO-DML is discussed elsewhere. 

doc/guide/modelling/TransformingToVODML.md

@@ -0,0 +1,8 @@
+Creating VO-DML from other Data Models
+======================================
+
+It is possible to start with an XML schema that can be transferred to VODSL with 
+
+```shell
+gradle vodmlXsdToVodsl --xsd mymodel.xsd --dsl mymodel.vodsl
+```

doc/guide/modelling/UML.md

@@ -3,8 +3,8 @@ UML
 
 ## Configuring the UML tool
 
-In general it is necessary to configure a UML tool with the IVOA "profile" to restrict the metamodel to that
-used by VO-DML.
+In general it is necessary to configure a UML tool with the IVOA "profile" to restrict
+the metamodel to that used by VO-DML.
 
 TBC
 

doc/guide/modelling/designIntro.md

@@ -1,4 +1,11 @@
 Designing Models
 ================
 
-## Testing serialization.
+Creating "good" data model designs is a art rather than a science. Within the context of the IVOA reusing existing recommended models is a prerequisite for a model be considered good.
+
+TBC
+
+## Testing serialization.
+
+The java runtime has some functionality for [roundtrip testing](../JavaCodeGeneration.md#testing-models) the various serializations 
+which can be a good first level test as to whether your model is a "good design".

doc/guide/modelling/modellingIntro.md

@@ -13,3 +13,29 @@ by editing in a text editor (and the [model schema](https://github.com/ivoa/vo-d
 * [VODSL](VODSL.md)
 * [UML](UML.md)
 
+
+It is possible to import existing data models by;
+
+1. Adding the published jar as a dependency in the `build.gradle.kts` file, e.g.
+```kotlin
+dependencies {
+    implementation("org.javastro.ivoa.vo-dml:ivoa-base:1.0")
+}
+```
+the tooling then makes sure that the model files are available for local import.
+1.  Importing into the model file, and there are two cases whether VO-DML or VODSL is considered the 'working source'
+
+    1. VO-DML - the tooling only requires the file name (it automatically creates an XML catalog which can resolve to  the absolute path)
+```xml
+<import>
+    <name>ivoa</name>
+    <url>IVOA-v1.0.vo-dml.xml</url>
+</import>
+
+```
+
+    1. VODSL - a relative path import should be used - the tooling automatically creates a vodsl file to import into the `build/tmp` directory so that the
+   exact form of the relative path depends on where the including source file is located.
+```
+include "../../build/tmp/IVOA-v1.0.vodsl"
+```

doc/mkdocs.yml

@@ -13,7 +13,7 @@ nav:
   - Getting Started:
       - Installation: Installation.md
       - Configuration: QuickStart.md
-  - Transformers:
+  - Derived Products:
       - Introduction: Transformers.md
       - Documentation: Documentation.md
       - Java Generation: JavaCodeGeneration.md
@@ -24,10 +24,13 @@ nav:
       - VODSL : modelling/VODSL.md
       - Eclipse Editor: modelling/EclipseVODSL.md
       - UML : modelling/UML.md
+      - Generation from other sources : modelling/TransformingToVODML.md
   - Model Design:
       - Introduction : modelling/designIntro.md
 
 markdown_extensions:
+  - admonition
+  - pymdownx.details
   - pymdownx.superfences:
       custom_fences:
         - name: mermaid