Editorial Pass on Constraint Documentation (usnistgov#555)

* Updated to use latest development version of the hugo theme.

* Adjusted definition spec to fix markdown formatting issues.

* Reorganized headings, added cross-links, added syntax table for common data elements.

* Completed editorial pass on constraint documentation.

* Update .env

.github/workflows/config/.env

@@ -1 +1 @@
-HUGO_VERSION=0.118.2
+HUGO_VERSION=0.120.0

.gitignore

@@ -17,6 +17,10 @@ nohup.out
 # Ignore NodeJS modules
 node_modules/
 
+# ignore Golang vendor modules
+/build/vendor/
+
 # Ignore XSpec reports and temp directories
 xspec/
 *report.html
+

website/config/_default/hugo.yaml

@@ -1,6 +1,5 @@
 title: "Metaschema"
 baseURL: https://pages.nist.gov/metaschema/
-canonifyURLs: true
 defaultContentLanguage: en
 languageCode: "en-us"
 MetaDataFormat: "yaml"
@@ -22,11 +21,13 @@ module:
   mounts:
   - source: static
     target: static
+  - source: static/img
+    target: assets/img
   - source: ../examples
     target: static/examples
   imports:
+  - path: github.com/usnistgov/hugo-uswds
   - path: github.com/usnistgov/hugo-uswds-nist
-relativeURLs: true # rewrites URLs to a relative form supporting link offline checking
 enableGitInfo: true # enable to get page modification dates for a site stored in Git
 params:
   header:

website/content/_index.md

@@ -7,13 +7,13 @@ cascade:
   sidenav:
     collapsedepth: 4
 ---
-{{< usa-hero image="automation-hero.png" calloutAltText="Efficient" calloutText="Information Modeling" buttonURL="/specification/" buttonText="Learn More" >}}
+{{% usa-hero image="automation-hero.png" calloutAltText="Efficient" calloutText="Information Modeling" buttonURL="/specification/" buttonText="Learn More" %}}
 Modeling information<br/>
 Quickly and Easily<br/>
 in Multiple Formats
-{{< /usa-hero >}}
+{{% /usa-hero %}}
 
-{{< usa-tagline caption="Maximizing your modeling efforts." >}}
+{{% usa-tagline caption="Maximizing your modeling efforts." %}}
 Metaschema provides a common, format-agnostic modeling framework supporting schema, code, and documentation generation *all in one*.
 
 Current modeling technologies (i.e. XML Schema, JSON Schema, Schematron) are:
@@ -40,4 +40,4 @@ Metaschema achieves this with:
 
 - A modeling abstraction that unifies the modeling and validation capabilities of existing schema and validation technologies.
 - Tools that automatically generate code, schemas, documentation, and format-appropriate content converters from Metaschema-based models.
-{{< /usa-tagline >}}
+{{% /usa-tagline %}}

website/content/specification/syntax/_index.md

@@ -6,7 +6,7 @@ weight: 30
 aliases:
 - /specification/syntax/
 custom_css:
-- /css/element-map.css
+- /metaschema/css/element-map.css
 ---
 
 # Metaschema Syntax

website/content/specification/syntax/definitions.md

@@ -169,12 +169,15 @@ field:
 
 ### `<remarks>`
 
-The optional `<remarks>` element provides a place to add notes related to the use of the definition. Remarks can be used to clarify the semantics of the definition in specific conditions, or to better describe how the definition may be more fully utilized within a model. 
+The optional `<remarks>` element provides a place to add notes related to the use of the definition. Remarks can be used to clarify the semantics of the definition in specific conditions, or to better describe how the definition may be more fully utilized within a model.
 
 The `<remarks>` element is optional and may occur multiple times.
+
 It supports an optional `@class` attribute that can be used to identify format specific remarks, to be handled appropriately (or ignored when not useful) in a downstream application. Valid values for `@class` are:
+
 - `XML`: The remark applies to the XML format binding.
 - `JSON`: The remark applies to the JSON or YAML format bindings.
+
 ### `<example>`
 
 The optional `<example>` element is used to provide inline examples, which illustrate the use of the information element being defined. Examples are provided in XML, which can then be automatically converted into other formats.

website/content/specification/syntax/metapath.md

@@ -0,0 +1,15 @@
+---
+title: "Metapath Expression Language"
+description: ""
+weight: 60
+---
+
+# Metapath Expression Language
+
+Metaschema includes support for an expression language called *Metapath*, which allows for selecting and evaluating Metaschema modules and data instances that conform to a Metaschema module. A Metapath can be used to query all Metaschema supported formats (i.e., JSON, YAML, XML) using a common, Metaschema module-bound syntax. This means a Metapth can be used to query the same data regardless of the underlying format used, as long as that data is bound to a Metaschema module. This provides consistent portability of Metapath expressions against multiple serialization forms for the same data set.
+
+Metapath is a customization of the [XML Path Language (XPath) 3.1](https://www.w3.org/TR/2017/REC-xpath-31-20170321/), which has been adjusted to work with a Metaschema module based model. This means the underlying [XML Data model](https://www.w3.org/TR/xpath-datamodel-31/) used by XPath, which exposes element and attribute nodes, is replaced with the Metaschema data model, which exposes flag, field, and assembly nodes.
+
+XPath was chosen as a basis for Metapath because it provides for both *selection* of nodes and logical *evaluation* of node values, the later of which is required for supporting Metaschema module [constraints](/specification/syntax/constraints). Other path languages (e.g., [JSON Path](https://goessner.net/articles/JsonPath/), [JSON Pointer](https://www.rfc-editor.org/rfc/rfc6901.html)) were not chosen, due to limitations in *evaluation* capabilities and because their syntax was specific to JSON.
+
+Note: Not all XPath features are supported by Metapath, the specifics of which will be documented in an updated version of this page in the future.

website/content/tutorials/_index.md

@@ -12,6 +12,6 @@ menu:
 The following tutorials provide walk-throughs for developers to understand Metaschema, its use cases, and how to use or develop news to exercise them.
 
 - [Tutorial #1:: Getting Started with Metaschema](1-getting-started/): Introduces the basics of Metaschema-based modeling using a "computer" model as an example.
-- [Tutorial #2: Using Constraints](2-constraints/): Introduces Metaschema constraints and how to use them for more precise control for values in model-based document instances.
+- [Tutorial #2: Using Constraints](2-constraints/): Introduces Metaschema constraints and how to use them for more precise control for values in model-based document instances. This tutorial introduces use of the `allowed-values` constraint.
 - [Tutorial #3: Complex Constraints: expect](3-constraints-expect/): Introduces advanced usage of Metaschema constraints, specifically `expect` and its common use cases.
-- [Tutorial #4: Complex Constraints: matches](4-constraints-matches/): Introduces advanced usage of Metaschema constraints, specifically `matches` and common its use cases.
+- [Tutorial #4: Complex Constraints: matches](4-constraints-matches/): Introduces advanced usage of Metaschema constraints, specifically `matches` and common its use cases.

website/go.mod

@@ -1,8 +1,10 @@
 module github.com/usnistgov/metaschema/website
 
-//replace github.com/usnistgov/hugo-uswds => ../../hugo-uswds
+// replace github.com/usnistgov/hugo-uswds => ../../../hugo/hugo-uswds
 
 go 1.21
 
 // TODO replace with official release
 require github.com/usnistgov/hugo-uswds-nist v0.0.0-20230921191202-abb701944c8d // indirect
+
+require github.com/usnistgov/hugo-uswds v1.0.1-0.20240227190543-44bb56d22269 // indirect

website/go.sum

@@ -1,3 +1,10 @@
+github.com/usnistgov/hugo-uswds v1.0.1-0.20230921190836-3c6b82fe7897 h1:pe/ejVy5P6w/me8tLLuZKOU3ARRy9FnpfIPprwyedXI=
 github.com/usnistgov/hugo-uswds v1.0.1-0.20230921190836-3c6b82fe7897/go.mod h1:pp3SuiZt0HVqXX8Z7EmEvhcht3+sR3vbPzm3SGiImsA=
+github.com/usnistgov/hugo-uswds v1.0.1-0.20240227124152-959dd59d0638 h1:UMsWlMJjH5dViraTKPPfBJd20tjwtOM2B+AajpsJ/U4=
+github.com/usnistgov/hugo-uswds v1.0.1-0.20240227124152-959dd59d0638/go.mod h1:pp3SuiZt0HVqXX8Z7EmEvhcht3+sR3vbPzm3SGiImsA=
+github.com/usnistgov/hugo-uswds v1.0.1-0.20240227134243-0647b823893f h1:qsQKk8TFsorhaKMJc6V9iwoAz3CeVt6zGh2mMxtntdk=
+github.com/usnistgov/hugo-uswds v1.0.1-0.20240227134243-0647b823893f/go.mod h1:pp3SuiZt0HVqXX8Z7EmEvhcht3+sR3vbPzm3SGiImsA=
+github.com/usnistgov/hugo-uswds v1.0.1-0.20240227190543-44bb56d22269 h1:5d6VxDkJK/V5zb1N46FkOuttQfByPUluh8sYAb5V5M8=
+github.com/usnistgov/hugo-uswds v1.0.1-0.20240227190543-44bb56d22269/go.mod h1:pp3SuiZt0HVqXX8Z7EmEvhcht3+sR3vbPzm3SGiImsA=
 github.com/usnistgov/hugo-uswds-nist v0.0.0-20230921191202-abb701944c8d h1:xQdUJk+874+KJ45UOUXIawujkuaAcSomfLsJCP/ouK8=
 github.com/usnistgov/hugo-uswds-nist v0.0.0-20230921191202-abb701944c8d/go.mod h1:6w0sCYV02SLdCL5Eu8QN10RWSDeYZzkFjJ7vIq8T/yc=