Further docs adjustments (#150)

* Further adjustments to definitions pages * Sorting definitions in docs by name; better display for grouping and other features; bug repair in (display) level assignment * Merged definition (item) display logic into single template
usnistgov · Jun 4, 2021 · 22591bd · 22591bd
1 parent 71331d0
commit 22591bd
Show file tree

Hide file tree

Showing 4 changed files with 100 additions and 67 deletions.
diff --git a/toolchains/xslt-M4/document/common-definitions.xsl b/toolchains/xslt-M4/document/common-definitions.xsl
@@ -11,7 +11,6 @@
     <xsl:key name="field-definition-by-name" match="/METASCHEMA/define-field"       use="@_key-name"/>
     <xsl:key name="flag-definition-by-name" match="/METASCHEMA/define-flag"         use="@_key-name"/>
 
-
     <xsl:variable name="datatype-page" as="xs:string">../../../datatypes</xsl:variable>
 
     <xsl:variable name="indenting" as="element()"
@@ -30,7 +29,9 @@
             <xsl:apply-templates select="short-name" mode="converter-link"/>
             <xsl:apply-templates select="remarks"/>
 
-            <xsl:apply-templates select="$definitions" mode="model-view"/>
+            <xsl:apply-templates select="$definitions" mode="model-view">
+                <xsl:sort select="(root-name,use-name,@name)[1]"/>
+            </xsl:apply-templates>
 
         </div>
     </xsl:template>
@@ -120,21 +121,38 @@
         match="define-field | field" expand-text="true">{ (use-name,@name,@ref)[1] }</xsl:template>
 
     <xsl:template match="root-name" expand-text="true">
-        <p>Name at root: <code class="use-name">{ . }</code></p>
+        <p><span class="usa-tag">root name</span>&#xA0;<code class="name">{ . }</code></p>
+    </xsl:template>
+
+    <xsl:template match="json-key" expand-text="true">
+        <p><span class="usa-tag">object key</span>&#xA0;<code class="name">{ . }</code></p>
+    </xsl:template>
+
+    <xsl:template match="json-value-key" expand-text="true">
+        <p><span class="usa-tag">value key</span>&#xA0;<code class="name">{ . }</code></p>
+    </xsl:template>
+
+    <xsl:template match="json-key[@flag-name]" expand-text="true">
+        <p><span class="usa-tag">object key flag</span>&#xA0;<code class="name">{ @flag-name }</code></p>
     </xsl:template>
 
-    <xsl:template match="/METASCHEMA/*/use-name" expand-text="true">
-        <p>May use name: <code class="name">{ . }</code></p>
+    <xsl:template match="json-value-key[@flag-name]" expand-text="true">
+        <p><span class="usa-tag">value key flag</span>&#xA0;<code class="name">{ @flag-name }</code></p>
     </xsl:template>
 
     <xsl:template match="use-name" expand-text="true">
-        <p>Use name: <code class="name">{ . }</code></p>
+        <p><span class="usa-tag">use name</span>&#xA0;<code class="name">{ . }</code></p>
     </xsl:template>
 
     <xsl:template match="group-as" expand-text="true">
-        <p>Grouping rule: group as <code class="name">{ @name }</code></p>
+        <p><span class="usa-tag">group as</span>&#xA0;<code class="name">{ @name }</code></p>
+        <p><span class="usa-tag">grouping object</span>&#xA0;<code class="name">{ (@in-json,'ARRAY')[1] }</code></p>
+        <xsl:if test="@in-xml='GROUPED'">
+            <p>When expressed in XML, a containing element <code class="name">{ @name }</code> is required.</p>
+        </xsl:if>
     </xsl:template>
 
+    <xsl:template match="example"/>
 
     <xsl:template match="define-flag" mode="model"/>
 
@@ -151,41 +169,42 @@
         </xsl:for-each-group>
     </xsl:template>
 
-    <xsl:template match="use-name" mode="inline" expand-text="true"> - using name <code>{ . }</code></xsl:template>
-
-    <xsl:template match="group-as" mode="inline" expand-text="true"> - grouped as <code>{ @name }</code></xsl:template>
-
-    <xsl:template match="define-assembly | define-field | define-flag" mode="model-view">
-        <xsl:variable name="level" select="count(. | ancestor::define-assembly)"/>
+    <xsl:template match="define-assembly | define-field | define-flag | assembly | field | flag" mode="model-view">
+        <xsl:variable name="level" select="count(. | ancestor::define-assembly | ancestor::define-field)"/>
+        <xsl:variable name="is-inline" select="exists(ancestor::model)"/>
+        <xsl:variable name="header-tag" select="if ($level le 6) then ('h' || $level) else 'p'"/>
+        <xsl:variable name="definition" as="element()">
+            <xsl:apply-templates select="." mode="find-definition"/>
+        </xsl:variable>
         <div class="model-entry definition { name() }"
             style="margin: 0em; margin-top: 1em; padding: 0.5em; border: thin solid black">
-            <div class="definition-header">
-                <xsl:element namespace="http://www.w3.org/1999/xhtml" name="h{ $level }"
+            <div class="{ if ($is-inline) then 'instance-header' else 'definition-header' }">
+                <xsl:element namespace="http://www.w3.org/1999/xhtml" name="{ $header-tag }"
                     expand-text="true">
                     <xsl:call-template name="mark-id"/>
-                    <xsl:attribute name="class">toc{ $level} head</xsl:attribute>
+                    <xsl:attribute name="class">toc{ $level} name</xsl:attribute>
                     <xsl:apply-templates select="." mode="definition-title-text"/>
                 </xsl:element>
                 <p class="type">
-                    <xsl:apply-templates select="." mode="metaschema-type"/>
+                    <xsl:apply-templates select="$definition" mode="metaschema-type"/>
                 </p>
-                <xsl:if test="exists(ancestor::model)">
+                <xsl:if test="$is-inline">
                     <p class="occurrence">
                         <xsl:apply-templates select="." mode="occurrence-code"/>
                     </p>
                 </xsl:if>
                 <xsl:call-template name="crosslink"/>
-                <xsl:apply-templates select="formal-name" mode="in-header"/>
+                <xsl:apply-templates select="$definition/formal-name" mode="in-header"/>
             </div>
-            <!-- in no mode for regular contents -->
+
+            <!-- in no mode for regular contents including use-name, group-as etc. -->
             <xsl:apply-templates/>
-            <!--            -->
+
+            <!-- emits contents only for define-assembly and define-field -->
             <xsl:apply-templates select="." mode="model"/>
 
-            <!--<details>
-                <summary>Metaschema source</summary>
-                <pre><xsl:value-of select="serialize(., $indenting)"/></pre>
-            </details>-->
+            <!-- emits contents only for references -->
+            <xsl:apply-templates select="." mode="link-to-definition"/>
         </div>
     </xsl:template>
 
@@ -194,38 +213,58 @@
         <xsl:message>not making crosslink...</xsl:message>
     </xsl:template>
 
-    <xsl:template match="assembly | field | flag" mode="model-view">
-        <xsl:variable name="level" select="count(ancestor-or-self::*[exists(@gi)])"/>
+    <!--<xsl:template match="assembly | field | flag" mode="model-view">
+        <xsl:variable name="level" select="count(. | ancestor::define-assembly | ancestor::define-field)"/>
         <xsl:variable name="header-tag" select="if ($level le 6) then ('h' || $level) else 'p'"/>
+        <xsl:variable name="definition" as="element()">
+            <xsl:apply-templates select="." mode="find-definition"/>
+        </xsl:variable>
         <div class="model-entry definition { name() }"
             style="margin: 0em; margin-top: 1em; padding: 0.5em; border: thin solid black">
-            <!--<xsl:call-template name="crosslink-to-xml"/>-->
-            <!-- generates h1-hx headers picked up by Hugo toc -->
             <div class="instance-header">
                 <xsl:element namespace="http://www.w3.org/1999/xhtml" name="h{ $level }"
                 expand-text="true">
                 <xsl:call-template name="mark-id"/>
-                <xsl:attribute name="class">toc{ $level} head</xsl:attribute>
+                <xsl:attribute name="class">toc{ $level} name</xsl:attribute>
                 <xsl:apply-templates select="." mode="definition-title-text"/>
             </xsl:element>
                 <p class="type">
-                    <xsl:apply-templates select="." mode="metaschema-type"/>
+                    <xsl:apply-templates select="$definition" mode="metaschema-type"/>
                 </p>
                 <xsl:if test="exists(ancestor::model)">
                     <p class="occurrence">
                         <xsl:apply-templates select="." mode="occurrence-code"/>
                     </p>
                 </xsl:if>
                 <xsl:call-template name="crosslink"/>
-                <xsl:apply-templates select="formal-name" mode="in-header"/>
+                <xsl:apply-templates select="$definition/formal-name" mode="in-header"/>
             </div>
-            <!-- placeholder for what is to come -->
+            <!-\- placeholder for what is to come -\->
             <xsl:apply-templates/>
             <xsl:apply-templates select="." mode="link-to-definition"/>
             
         </div>
+    </xsl:template>-->
+
+    <xsl:template mode="find-definition" as="element()" match="define-assembly | define-field | define-flag">
+        <xsl:sequence select="."/>
+    </xsl:template>
+
+    <xsl:template mode="find-definition" as="element()" match="assembly">
+        <xsl:sequence select="key('assembly-definition-by-name',@_key-ref)"/>
+    </xsl:template>
+
+    <xsl:template mode="find-definition" as="element()" match="field">
+        <xsl:sequence select="key('field-definition-by-name',@_key-ref)"/>
     </xsl:template>
 
+    <xsl:template mode="find-definition" as="element()" match="flag">
+        <xsl:sequence select="key('flag-definition-by-name',@_key-ref)"/>
+    </xsl:template>
+
+    <!-- Don't need links to themselves. -->
+    <xsl:template match="define-assembly | define-field | define-flag" mode="link-to-definition"/>
+
     <xsl:template match="*" mode="link-to-definition">
         <xsl:comment> link to definition goes here </xsl:comment>
         <xsl:message>not making link to definition...</xsl:message>
@@ -255,13 +294,11 @@
     </xsl:template>
 
     <xsl:template priority="5" match="choice">
-        <li class="choice">
+        <div class="choice">
             <xsl:call-template name="mark-id"/>
-            <xsl:text>A choice between: </xsl:text>
-            <ul>
-                <xsl:apply-templates/>
-            </ul>
-        </li>
+            <p>A choice between: </p>
+            <xsl:apply-templates/>
+        </div>
     </xsl:template>
 
     <xsl:template match="remarks">

diff --git a/toolchains/xslt-M4/document/common-reference.xsl b/toolchains/xslt-M4/document/common-reference.xsl
@@ -190,7 +190,7 @@
    </xsl:template>
 
    <xsl:template match="*" mode="report-context" expand-text="true">
-      <xsl:for-each select="@target[not(.=('.','value()')) ]">
+      <xsl:for-each select="@target[matches(.,'\S')][not(.=('.','value()')) ]">
          <xsl:text>  for </xsl:text>
          <code class="path">{ . }</code>
       </xsl:for-each>
@@ -203,7 +203,7 @@
    </xsl:template>
 
    <xsl:template mode="produce-constraint" priority="2" match="matches[@regex]" expand-text="true">
-      <xsl:variable name="target" select="@target[not(.=('.','value()'))]"/>
+      <xsl:variable name="target" select="@target[matches(.,'\S')][not(.=('.','value()'))]"/>
       <div class="constraint">
          <p>
             <span class="usa-tag">matches</span>
@@ -223,7 +223,7 @@
    </xsl:template>
 
    <xsl:template mode="produce-constraint" priority="2" match="is-unique">
-      <xsl:variable name="target" select="@target[not(.=('.','value()'))]"/>
+      <xsl:variable name="target" select="@target[matches(.,'\S')][not(.=('.','value()'))]"/>
       <div class="constraint">
          <p>
             <span class="usa-tag">is unique</span>
@@ -238,9 +238,8 @@
          <p>
             <span class="usa-tag">has cardinality</span>
             <xsl:apply-templates select="." mode="report-context"/>
-            <span class="cnstr-tag">cardinality rule</span>
             <xsl:text> the cardinality of  </xsl:text>
-            <code>{ (@target,'.')[1] }</code>
+            <code>{ (@target[matches(.,'\S')],'.')[1] }</code>
             <xsl:text> is constrained: </xsl:text>
             <b>{ (@min-occurs,0)[1] }</b>
             <xsl:text>; maximum </xsl:text>
@@ -249,12 +248,11 @@
    </xsl:template>
 
    <xsl:template mode="produce-constraint" priority="2" match="index-has-key" expand-text="true">
-      <xsl:variable name="target" select="@target[not(.=('.','value()'))]"/>
+      <xsl:variable name="target" select="@target[matches(.,'\S')][not(.=('.','value()'))]"/>
       <div class="constraint">
          <p>
             <span class="usa-tag">index has key</span>
             <xsl:apply-templates select="." mode="report-context"/>
-            <span class="cnstr-tag">index rule</span>
             <xsl:text>this value must correspond to a listing in the index </xsl:text>
             <code>{ @name }</code>
             <xsl:text> using a key constructed of key field(s) </xsl:text>
@@ -268,11 +266,10 @@
          <p>
             <span class="usa-tag">index</span>
             <xsl:apply-templates select="." mode="report-context"/>
-            <span class="cnstr-tag">index definition</span>
             <xsl:text> an index </xsl:text>
             <code>{ @name }</code>
             <xsl:choose>
-               <xsl:when test="matches(@target,'\S')">
+               <xsl:when test="matches(@target,'\S') and not(@target=('.','value()'))">
                   <xsl:text> shall list values returned by targets </xsl:text>
                   <code>{ @target }</code>
                </xsl:when>

diff --git a/toolchains/xslt-M4/document/json/json-definitions.xsl b/toolchains/xslt-M4/document/json/json-definitions.xsl
@@ -55,22 +55,23 @@ exclude-result-prefixes="#all">
       </div>
    </xsl:template>
 
-   <xsl:template mode="metaschema-type" match="define-assembly | define-field | define-flag">
-      <xsl:text expand-text="true">{ local-name() => replace('^define\-','') } definition</xsl:text><br class="br" />
-      <xsl:variable name="definition" select="()"/>
-      <xsl:if test="exists($definition)">
-         <xsl:text> </xsl:text>
-         <a class="definition-link" href="#{ @_metaschema-json-id }">(global definition)</a>
-      </xsl:if>
+   <xsl:template mode="metaschema-type" match="define-assembly">
+      <xsl:text expand-text="true">assembly</xsl:text><br class="br" />
+      <xsl:text> </xsl:text>
    </xsl:template>
 
    <xsl:template mode="metaschema-type" match="assembly | field | flag">
-      <xsl:value-of select="local-name()"/><br class="br"/>
-      <xsl:variable name="definition" select="()"/>
+      <xsl:variable name="definition" as="element()">
+         <xsl:apply-templates select="." mode="find-definition"/>
+      </xsl:variable>
+      <xsl:apply-templates select="$definition" mode="metaschema-type"/>
+      <br class="br"/>
       <xsl:if test="exists($definition)">
          <xsl:text> </xsl:text>
          <a class="definition-link" href="#{ @_metaschema-json-id }">(global definition)</a>
       </xsl:if>
    </xsl:template>
 
+
+
 </xsl:stylesheet>
diff --git a/toolchains/xslt-M4/document/xml/xml-definitions.xsl b/toolchains/xslt-M4/document/xml/xml-definitions.xsl
@@ -57,23 +57,21 @@ exclude-result-prefixes="#all">
         </div>
     </xsl:template>
 
-    <xsl:template mode="metaschema-type" match="define-assembly | define-field | define-flag">
-        <xsl:text expand-text="true">{ local-name() => replace('^define\-','') } definition</xsl:text><br class="br" />
-        <xsl:variable name="definition" select="()"/>
-        <xsl:if test="exists($definition)">
-            <xsl:text> </xsl:text>
-            <a class="definition-link" href="#{ @_metaschema-xml-id }">(global definition)</a>
-        </xsl:if>
+    <xsl:template mode="metaschema-type" match="define-assembly">
+        <xsl:text expand-text="true">assembly</xsl:text><br class="br" />
+        <xsl:text> </xsl:text>
     </xsl:template>
 
     <xsl:template mode="metaschema-type" match="assembly | field | flag">
-        <xsl:value-of select="local-name()"/><br class="br"/>
-        <xsl:variable name="definition" select="()"/>
+        <xsl:variable name="definition" as="element()">
+            <xsl:apply-templates select="." mode="find-definition"/>
+        </xsl:variable>
+        <xsl:apply-templates select="$definition" mode="metaschema-type"/>
+        <br class="br"/>
         <xsl:if test="exists($definition)">
             <xsl:text> </xsl:text>
             <a class="definition-link" href="#{ @_metaschema-xml-id }">(global definition)</a>
         </xsl:if>
     </xsl:template>
 
-
 </xsl:stylesheet>