Use external link for Metaschema types, make base url overrideable Fixed

#15 (#70) --------- Co-authored-by: Nikita Wootten <nikita.wootten@nist.gov>
usnistgov · Sep 21, 2023 · 66d2965 · 66d2965
1 parent aaaba3c
commit 66d2965
Show file tree

Hide file tree

Showing 9 changed files with 406 additions and 47 deletions.
diff --git a/src/common/datatypes.xsl b/src/common/datatypes.xsl
@@ -0,0 +1,55 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<xsl:stylesheet xmlns:m="http://csrc.nist.gov/ns/oscal/metaschema/1.0"
+                xmlns:xs="http://www.w3.org/2001/XMLSchema"
+                xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+                version="3.0">
+    <!--
+         Normalize deprecated datatype names
+         ex. m:datatype-normalize('dateTime-with-timezone') => date-time-with-timezone
+         Note: unknown and valid datatypes will be passed along as-is
+    -->
+    <xsl:function
+        name="m:datatype-normalize" as="xs:string">
+        <xsl:param name="raw-datatype" as="xs:string" />
+        <xsl:variable name="deprecation-map">
+            <!-- these old names are permitted for now, while only deprecated -->
+            <!--metaschema/schema/xml/metaschema.xsd
+                 line 1052 inside  /*/xs:simpleType[@name='SimpleDatatypesType']> -->
+            <entry key="base64Binary">base64</entry>
+            <entry key="dateTime">date-time</entry>
+            <entry key="dateTime-with-timezone">date-time-with-timezone</entry>
+            <entry key="email">email-address</entry>
+            <entry key="nonNegativeInteger">non-negative-integer</entry>
+            <entry key="positiveInteger">positive-integer</entry>
+        </xsl:variable>
+        <xsl:choose>
+            <xsl:when test="$deprecation-map/entry[@key=$raw-datatype]">
+                <xsl:value-of select="$deprecation-map/entry[@key=$raw-datatype]"/>
+            </xsl:when>
+            <xsl:otherwise>
+                <xsl:value-of select="$raw-datatype"/>
+            </xsl:otherwise>
+        </xsl:choose>
+    </xsl:function>
+
+    <!-- used in documentation generation pipelines -->
+    <xsl:param name="metaschema-reference-url" as="xs:string">https://pages.nist.gov/metaschema/specification/datatypes</xsl:param>
+
+    <!--
+         Create an href link to the metaschema documentation for a given datatype
+         Warning this function makes no attempt to validate datatype names, only fixing explicitly deprecated names.
+    -->
+    <xsl:function name="m:datatype-create-link" as="element()">
+        <xsl:param name="raw-datatype" as="xs:string" />
+        <xsl:variable name="datatype" as="xs:string" select="m:datatype-normalize($raw-datatype)" />
+
+        <xsl:element name="a">
+            <xsl:attribute name="href">
+                <xsl:value-of select="$metaschema-reference-url"/>
+                <xsl:text>/#</xsl:text>
+                <xsl:value-of select="$datatype"/>
+            </xsl:attribute>
+            <xsl:value-of select="$datatype"/>
+        </xsl:element>
+    </xsl:function>
+</xsl:stylesheet>
diff --git a/src/document/common/common-definitions.xsl b/src/document/common/common-definitions.xsl
@@ -6,13 +6,12 @@
     exclude-result-prefixes="#all">
 
     <xsl:import href="common-reference.xsl"/>
+    <xsl:import href="../../common/datatypes.xsl"/>
 
     <xsl:key name="assembly-definition-by-name" match="/METASCHEMA/define-assembly" use="@_key-name"/>
     <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">/reference/datatypes</xsl:variable>
-
+
     <xsl:variable name="indenting" as="element()"
         xmlns:output="http://www.w3.org/2010/xslt-xquery-serialization">
         <output:serialization-parameters>
@@ -238,10 +237,10 @@
 
     <!-- override this -->
     <xsl:template mode="metaschema-type" match="*" expand-text="true">{ local-name() }</xsl:template>
-        
+
     <!-- expect overriding XSLT to provide metaschema type with appropriate link  -->
     <xsl:template mode="metaschema-type" match="*[exists(@as-type)]" expand-text="true">
-        <a href="{$datatype-page}/#{(lower-case(@as-type))}">{ @as-type }</a>
+        <xsl:sequence select="m:datatype-create-link(@as-type)"/>
     </xsl:template>
 
     <xsl:template priority="5" match="choice">

diff --git a/src/document/json/json-docs-hugo-uswds.xsl b/src/document/json/json-docs-hugo-uswds.xsl
@@ -19,8 +19,6 @@
 
    <xsl:variable name="metaschema-code" select="/*/short-name || '-json'"/>
 
-   <xsl:variable name="datatype-page" as="xs:string"> /reference/datatypes</xsl:variable>
-
    <xsl:strip-space elements="*"/>
 
    <xsl:preserve-space elements="p li pre i b em strong a code q"/>
@@ -1182,19 +1180,17 @@
       <xsl:apply-templates select="key('assembly-definitions', @ref)" mode="#current"/>
    </xsl:template>
 
+   <xsl:import href="../../common/datatypes.xsl"/>
+
    <xsl:template mode="metaschema-type" match="define-field[empty(flag | define-flag)]">
       <xsl:variable name="given-type" select="(@as-type, 'string')[1]"/>
-      <a href="{$datatype-page}/#{(lower-case($given-type))}">
-         <xsl:apply-templates mode="#current" select="$given-type"/>
-      </a>
+      <xsl:sequence select="m:datatype-create-link($given-type)"/>
    </xsl:template>
 
    <xsl:template mode="metaschema-type" match="flag | define-flag">
       <xsl:variable name="given-type"
          select="(@as-type, key('flag-definitions', @ref, $home)/@as-type, 'string')[1]"/>
-      <a href="{$datatype-page}/#{(lower-case($given-type))}">
-         <xsl:apply-templates mode="#current" select="$given-type"/>
-      </a>
+      <xsl:sequence select="m:datatype-create-link(@given-type)"/>
    </xsl:template>
 
    <xsl:variable name="numeric-types"

diff --git a/src/document/json/object-map-html.xsl b/src/document/json/object-map-html.xsl
@@ -5,6 +5,7 @@
    xmlns:m="http://csrc.nist.gov/ns/oscal/metaschema/1.0"
    exclude-result-prefixes="#all">
 
+   <xsl:import href="../../common/datatypes.xsl"/>
 
    <xsl:output omit-xml-declaration="true" indent="yes"/>
 
@@ -16,9 +17,7 @@
    <xsl:variable name="path-to-common">
       <xsl:for-each select="tokenize($outline-page,'/')">../</xsl:for-each>
    </xsl:variable>
-   <xsl:variable name="reference-link" select="$path-to-common || $reference-page"/>
-
-   <xsl:variable name="datatype-page">/reference/datatypes</xsl:variable>
+   <xsl:variable name="reference-link" select="$path-to-common || $reference-page"/> 
 
    <xsl:template match="/" mode="make-page">
       <html lang="en">
@@ -217,8 +216,7 @@ details:not([open]) .show-closed { display: inline }
       <xsl:if test="empty(@_tree-json-id)">
          <xsl:message expand-text="true">not seeing json tree id for { name(.) }</xsl:message>
       </xsl:if>
-      <xsl:variable as="xs:string" name="url-stem" select="replace($reference-link, '.html', '/')" />
-      <a class="OM-name" href="{ $url-stem }#{  @_tree-json-id }">
+      <a class="OM-name" href="{ $reference-link }#{  @_tree-json-id }">
          <xsl:value-of select="(@key,@gi,@name)[1]"/>
       </a>
    </xsl:template>
@@ -279,7 +277,9 @@ details:not([open]) .show-closed { display: inline }
    </xsl:template>
 
    <xsl:template priority="2" mode="inline-link-to" match="m:string" expand-text="true">
-      <span class="OM-datatype"><a href="{$datatype-page}/#{lower-case(@as-type)}">{ @as-type }</a></span>
+      <span class="OM-datatype">
+         <xsl:sequence select="m:datatype-create-link(@as-type)"/>
+      </span>
    </xsl:template>
 
    <xsl:template mode="contents" match="m:array | m:object | m:singleton-or-array | m:group-by-key">

diff --git a/src/document/json/object-reference-html.xsl b/src/document/json/object-reference-html.xsl
@@ -4,6 +4,9 @@
    xpath-default-namespace="http://csrc.nist.gov/ns/oscal/metaschema/1.0"
    xmlns:m="http://csrc.nist.gov/ns/oscal/metaschema/1.0" exclude-result-prefixes="#all">
 
+   <xsl:import href="../../common/datatypes.xsl"/>
+   <xsl:import href="../common/common-reference.xsl"/>
+
    <xsl:output indent="true"/>
    <!-- produces an HTML 'stub' to be inserted into Hugo -->
 
@@ -12,8 +15,6 @@
    <xsl:param name="json-map-page"> json/outline</xsl:param>
    <xsl:param name="json-definitions-page">json/definitions</xsl:param>
 
-   <xsl:variable name="datatype-page" as="xs:string">/reference/datatypes</xsl:variable>
-
    <xsl:template match="metadata/namespace"/>
 
    <xsl:template name="remarks-group">
@@ -182,7 +183,7 @@
    </xsl:template>
 
    <xsl:template mode="metaschema-type" match="*[exists(@as-type)]" expand-text="true">
-      <a href="{$datatype-page}/#{(lower-case(@as-type))}">{ @as-type }</a>
+      <xsl:sequence select="m:datatype-create-link(@as-type)"/>
    </xsl:template>
 
    <xsl:template match="*" mode="report-context" expand-text="true">
@@ -192,9 +193,6 @@
       </xsl:for-each>
    </xsl:template>
 
-
-   <xsl:import href="../common/common-reference.xsl"/>
-
    <xsl:template name="crosslink-to-xml">
       <div class="crosslink">
          <a class="usa-button" href="{$xml-reference-link}#{@_tree-xml-id}">Switch to XML</a>