Skip to content

Commit

Permalink
More enhancements to generated docs: usnistgov#423, usnistgov#424
Browse files Browse the repository at this point in the history
  • Loading branch information
@wendellpiez
wendellpiez committed Jul 23, 2019
1 parent 5ca108a commit 7c35228
Show file tree
Hide file tree
Showing 6 changed files with 83 additions and 42 deletions.
6 changes: 5 additions & 1 deletion build/metaschema/lib/metaschema-check.sch
View file
Original file line number Diff line number Diff line change
Expand Up @@ -114,7 +114,7 @@
<sqf:add target="group-as" node-type="element"><group-as name="{ $group-name }"/></sqf:add>
</sqf:fix>-->

</sch:rule>

<sch:rule context="m:group-as">
Expand All @@ -130,6 +130,10 @@
<sch:let name="ns" value="/m:METASCHEMA/m:namespace"/>
<sch:assert test="empty($example-ns) or namespace-uri(.) eq $example-ns">Unexpected namespace: examples should use namespace '<sch:value-of select="$example-ns"/>'</sch:assert>
</sch:rule>

<sch:rule context="m:p">
<sch:assert test="matches(.,'\S')">Empty paragraph (is likely to distort rendition)</sch:assert>
</sch:rule>
</sch:pattern>

<sch:pattern>
Expand Down
14 changes: 9 additions & 5 deletions build/metaschema/lib/metaschema-common-html.xsl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,13 +12,17 @@
</xsl:template>

<xsl:template match="m:description" mode="model">
<xsl:text>: </xsl:text>
<xsl:apply-templates/>
<br class="br"/>
<i style="font-size: smaller">
<xsl:apply-templates/>
</i>
</xsl:template>

<xsl:template match="m:remarks/m:p" mode="model">
<br/>
<xsl:apply-templates/>
<br class="br"/>
<span style="font-size: smaller">
<xsl:apply-templates/>
</span>
</xsl:template>

<xsl:template match="m:choice">
Expand Down Expand Up @@ -60,7 +64,7 @@
</xsl:template>

<xsl:template match="m:remarks">
<div class="remarks">
<div class="remarks usa-color-gray-lightest" style="padding: 0.5em">
<xsl:apply-templates/>
</div>
</xsl:template>
Expand Down
5 changes: 2 additions & 3 deletions build/metaschema/lib/metaschema-compose.xsl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -166,10 +166,10 @@
<xsl:copy-of select="$me-and-mine[last()]/description"/>
<xsl:apply-templates mode="#current" select="json-key, json-value-key, flag"/>
<xsl:copy-of select="$me-and-mine[last()]/valid-values"/>
<xsl:copy-of select="model"/>
<xsl:apply-templates mode="#current" select="$me-and-mine/remarks">
<xsl:sort select="position()" order="descending"/><!-- reversing the order -->
</xsl:apply-templates>
<xsl:copy-of select="model"/>
<xsl:apply-templates mode="#current" select="$me-and-mine/example">
<xsl:sort select="position()" order="descending"/><!-- reversing the order -->
</xsl:apply-templates>
Expand Down Expand Up @@ -202,8 +202,7 @@

<xsl:template mode="digest" match="flag | json-key | json-value-key">
<xsl:copy>
<xsl:attribute name="datatype">string</xsl:attribute>
<xsl:copy-of select="key('definition-by-name',@name)/@datatype"/>
<xsl:copy-of select="key('definition-by-name',@name)/@as-type"/>
<!-- Allowing local datatype to override the definition's datatype -->
<xsl:copy-of select="@*"/>
<xsl:apply-templates mode="#current"/>
Expand Down
18 changes: 18 additions & 0 deletions build/metaschema/lib/metaschema-jsondocs-jekyll-uswds.xsl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -379,6 +379,24 @@
</li>
</xsl:template>

<!-- remarks are kept if @class='xml' or no class is given -->
<xsl:template match="remarks[@class != 'json']" priority="2"/>

<xsl:template match="define-assembly/remarks | define-field/remarks | define-flag/remarks">
<xsl:if test="empty(preceding-sibling::remarks[not(@class != 'xml')])">
<h5>Remarks</h5>
</xsl:if>
<xsl:next-match/>
</xsl:template>

<xsl:template match="remarks[@class = 'json']/p[1]">
<p class="p">
<span class="usa-label">JSON</span>
<xsl:text> </xsl:text>
<xsl:apply-templates/>
</p>
</xsl:template>

<xsl:template match="example[empty(* except (description | remarks))]"/>

<xsl:template match="example">
Expand Down
76 changes: 45 additions & 31 deletions build/metaschema/lib/metaschema-xmldocs-jekyll-uswds.xsl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -103,6 +103,7 @@
select="@name"/> attribute</h4>
<xsl:call-template name="cross-links"/>
</header>
<xsl:apply-templates mode="state-type" select="."/>
<xsl:apply-templates select="description"/>
<xsl:for-each-group select="key('references',@name)/parent::*" group-by="true()">
<p><xsl:text>This attribute appears on: </xsl:text>
Expand Down Expand Up @@ -133,14 +134,7 @@
<xsl:apply-templates select="@name"/> element</h4>
<xsl:call-template name="cross-links"/>
</header>
<xsl:choose>
<xsl:when test="@as-type = 'markup-line'">
<p>Supports inline encoding</p>
</xsl:when>
<xsl:when test="@as-type = 'markup-multiline'">
<p>Appears as a sequence of markup elements (paragraphs, lists etc.)</p>
</xsl:when>
</xsl:choose>
<xsl:apply-templates mode="state-type" select="."/>
<xsl:apply-templates select="formal-name | description"/>
<xsl:call-template name="appears-in"/>
<xsl:if test="exists(flag)">
Expand All @@ -161,14 +155,11 @@
</xsl:choose>
</xsl:variable>
<div class="model">
<p xsl:expand-text="true">The {@name} element { $modal } have { $noun }:</p>
<p xsl:expand-text="true">The <code>{@name}</code> element { $modal } have { $noun }:</p>
<ul>
<xsl:apply-templates select="flag" mode="model"/>
</ul>
</div>
<!--<xsl:call-template name="uswds-table">
<xsl:with-param name="property-set" select="flag"/>
</xsl:call-template>-->
</xsl:if>
<xsl:apply-templates select="remarks"/>
<xsl:apply-templates select="example"/>
Expand Down Expand Up @@ -204,7 +195,6 @@
<xsl:apply-templates select="model"/>
<xsl:apply-templates select="remarks"/>
<xsl:apply-templates select="example"/>

</div>
</xsl:template>

Expand All @@ -224,15 +214,14 @@

<xsl:template match="flag" mode="model">
<li>
<xsl:apply-templates mode="link-here" select="key('definitions',@ref)"/>

<xsl:apply-templates mode="link-here" select="key('definitions',@ref)"/>
<xsl:if test="empty(@ref)">
<xsl:apply-templates select="@name"/>
</xsl:if>
<xsl:text> attribute </xsl:text>
<xsl:apply-templates select="@datatype"/>
<xsl:apply-templates select="@required"/>
<xsl:if test="not(@required) and self::flag"> (<i>optional</i>)</xsl:if>
<xsl:if test="empty(@required)"> (<i>optional</i>)</xsl:if>
<xsl:apply-templates select="." mode="metaschema-type"/>
<xsl:apply-templates select="if (description) then description else key('definitions', @name)/description" mode="model"/>
<xsl:if test="valid-values or key('definitions', @ref)/valid-values">
<xsl:apply-templates select="if (valid-values) then valid-values else key('definitions', @ref)/valid-values"/>
Expand All @@ -245,22 +234,23 @@
<i> (required)</i>
</xsl:template>

<!-- Empty model elements (whether by accident or design) will be dropped.
NB: at a later point, we may support model/@acquire-from
at present we have @acquire-from only on definitions. -->
<xsl:template match="model[not(*)]" priority="3"/>

<xsl:template match="model">
<div class="model">
<p>The <xsl:apply-templates select="../@name"/> element has the following contents<xsl:if
test="count(*) > 1"> (in order)</xsl:if>:</p>
<ul>
<xsl:apply-templates select="../flag | ../key" mode="model"/>
<xsl:apply-templates select="../flag" mode="model"/>
<xsl:apply-templates/>
</ul>
</div>
</xsl:template>

<xsl:template match="any">
<li>Any element (in a foreign namespace)</li>
</xsl:template>

<xsl:template match="assembly | field">
<li>
<!--<xsl:text>A</xsl:text>
Expand All @@ -271,7 +261,7 @@
</a>
<xsl:text expand-text="true"> element{ if (@max-occurs != '1') then 's' else '' } </xsl:text>
<xsl:apply-templates select="." mode="occurrence-requirements"/>

<xsl:apply-templates select="." mode="metaschema-type"/>
<xsl:apply-templates select="if (description) then description else key('definitions', @ref)/description" mode="model"/>
<xsl:if test="valid-values or key('definitions', @ref)/valid-values">
<xsl:apply-templates select="if (valid-values) then valid-values else key('definitions', @ref)/valid-values"/>
Expand All @@ -281,15 +271,23 @@
</xsl:template>

<!-- remarks are kept if @class='xml' or no class is given -->
<xsl:template match="remarks[@class != 'xml']"/>
<xsl:template match="remarks[@class != 'xml']" priority="2"/>

<xsl:template match="define-assembly/remarks | define-field/remarks | define-flag/remarks">
<xsl:if test="empty(preceding-sibling::remarks) or not(preceding-sibling::remarks/@class='xml')">
<xsl:if test="empty(preceding-sibling::remarks[not(@class != 'xml')])">
<h5>Remarks</h5>
</xsl:if>
<xsl:next-match/>
</xsl:template>

<xsl:template match="remarks[@class = 'xml']/p[1]">
<p class="p">
<span class="usa-label">XML</span>
<xsl:text> </xsl:text>
<xsl:apply-templates/>
</p>
</xsl:template>

<xsl:template match="example[empty(* except (description | remarks))]"/>

<xsl:template match="example">
Expand Down Expand Up @@ -413,15 +411,31 @@
</i>
</xsl:template>

<xsl:template match="define-flag" mode="state-type">
<p>An attribute<xsl:apply-templates select="." mode="metaschema-type"/></p>
</xsl:template>

<xsl:template match="define-field" mode="state-type">
<p>An element<xsl:apply-templates select="." mode="metaschema-type"/></p>
</xsl:template>

<xsl:template match="field | assembly" mode="metaschema-type">
<xsl:apply-templates select="key('definitions',@ref)" mode="#current"/>
</xsl:template>

<xsl:template mode="metaschema-type" match="flag | define-flag | define-field[exists(@as-type)]">
<xsl:text>, type </xsl:text>
<b>
<xsl:apply-templates mode="#current" select="@as-type"/>
<xsl:if test="empty(@as-type)">string</xsl:if>
</b>
</xsl:template>


<xsl:template mode="metaschema-type" match="flag">attribute</xsl:template>
<xsl:template mode="metaschema-type" match="field">element (with text contents)</xsl:template>
<xsl:template mode="metaschema-type" match="field[@as-type='markup-line']">element (with mixed text and element contents)</xsl:template>
<xsl:template mode="metaschema-type" match="field[@as-type='markup-multiline']">prose content: paragraphs, lists etc.</xsl:template>
<xsl:template mode="metaschema-type" match="assembly">element (with element contents)</xsl:template>
<xsl:template mode="metaschema-type" match="any">ANY</xsl:template>
<xsl:template mode="metaschema-type" match="description | remarks"/>
<xsl:template mode="metaschema-type" match="define-field">, with text contents</xsl:template>
<xsl:template mode="metaschema-type" match="*[@as-type='markup-line']" priority="2">, with mixed text and (inline prose) element contents</xsl:template>
<xsl:template mode="metaschema-type" match="*[@as-type='markup-multiline']" priority="2">, as prose content: paragraphs, lists etc.</xsl:template>
<xsl:template mode="metaschema-type" match="define-assembly">, with its element contents</xsl:template>

<xsl:template match="*" mode="metaschema-type">
<xsl:message>Matching <xsl:value-of select="local-name()"/></xsl:message>
Expand Down
6 changes: 4 additions & 2 deletions docs/content/documentation/relations.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
title: Relations to Industry Standards
title: Relations to Documentary Encoding Standards
description: Relations
permalink: /docs/relations/
layout: post
Expand All @@ -10,7 +10,9 @@ sticky_sidenav: true

Professionals working in the security domain are already familiar with numerous standards, specifications, guidelines and regulatory frameworks that define and describe practice in the systems security arena: NIST SP800-53, ISO 27001/2, FedRAMP, FISMA/FIPS, HIPAA and others. OSCAL's models are designed to capture the full range of these.

However, there are other standard forms of document represention that might also be useful in certain contexts. Since OSCAL attempts not to replace any of these, but to complement them, developers of OSCAL-based systems may wish to be aware of them and of opportunities to take advantage of OSCAL in working with them.
However, OSCAL is not the only text encoding technology available, and it is not always the most suitable, depending on the task at hand. Designed specifically to support operations related to security automation and assessment support, OSCAL may not be as optimal as other (standards-based, non-proprietary) formats for other applications including, notably, full text transcription, search and retrieval, or publication workflows. (OSCAL data may be shared among partners, even over networks including the Internet; but it is not necessarily suitable for publishing as such.)

More importantly, since OSCAL shares its technical foundations with other documentary encoding standards that serve other horizontal or neighboring vertical domains, it is important to recognize a *high degree of compatibility* with other XML-based formats. Investing in OSCAL and OSCAL-related tooling is a way of developing capability that applies to these other formats as well; likewise investing in these can have beneficial side effects related to OSCAL and related technologies.

## How OSCAL relates to other document encoding formats

Expand Down

0 comments on commit 7c35228

Please sign in to comment.