metanorma-nist 0.0.1

data/lib/asciidoctor/nist/converter.rb

@@ -0,0 +1,271 @@
+require "asciidoctor"
+require "asciidoctor/nist"
+require "asciidoctor/standoc/converter"
+require "isodoc/nist/html_convert"
+require "isodoc/nist/word_convert"
+require_relative "front"
+require "fileutils"
+
+module Asciidoctor
+  module NIST
+    class Converter < Standoc::Converter
+
+      register_for "nist"
+
+      def title_validate(root)
+        nil
+      end
+
+      def example(node)
+        return pseudocode_example(node) if node.attr("style") == "pseudocode"
+        return recommendation(node) if node.attr("style") == "recommendation"
+        return requirement(node) if node.attr("style") == "requirement"
+        return permission(node) if node.attr("style") == "permission"
+        super
+      end
+
+      def pseudocode_example(node)
+        noko do |xml|
+          xml.figure **{id: Asciidoctor::Standoc::Utils::anchor_or_uuid(node), 
+                         type: "pseudocode"} do |ex|
+                        figure_title(node, ex)
+            wrap_in_para(node, ex)
+          end
+        end.join("\n")
+      end
+
+      def recommendation(node)
+        noko do |xml|
+          xml.recommendation **id_attr(node) do |ex|
+            wrap_in_para(node, ex)
+          end
+        end.join("\n")
+      end
+
+      def requirement(node)
+        noko do |xml|
+          xml.requirement **id_attr(node) do |ex|
+            wrap_in_para(node, ex)
+          end
+        end.join("\n")
+      end
+
+      def permission(node)
+        noko do |xml|
+          xml.permission **id_attr(node) do |ex|
+            wrap_in_para(node, ex)
+          end
+        end.join("\n")
+      end
+
+      def table(node)
+        return errata(node) if node.attr("style") == "errata"
+        super
+      end
+
+      def errata(node)
+        cols = []
+        node.rows[:head][-1].each { |c| cols << c.text.downcase }
+        table = []
+        node.rows[:body].each do |r|
+          row = {}
+          r.each_with_index do |c, i|
+            row[cols[i]] = c.content.join("")
+          end
+          table << row
+        end
+        noko do |xml|
+          xml.errata do |errata|
+            table.each do |entry|
+              errata.row do |row|
+                row.date { |x| x << entry["date"] }
+                row.type { |x| x << entry["type"] }
+                row.change { |x| x << entry["change"] }
+                row.pages { |x| x << entry["pages"] }
+              end
+            end
+          end
+        end
+      end
+
+            def dlist(node)
+              return glossary(node) if node.attr("style") == "glossary"
+              super
+            end
+
+            def glossary(node)
+        noko do |xml|
+          xml.dl **{id: Asciidoctor::Standoc::Utils::anchor_or_uuid(node),
+                         type: "glossary"} do |xml_dl|
+            node.items.each do |terms, dd|
+              dt(terms, xml_dl)
+              dd(dd, xml_dl)
+            end
+          end
+        end.join("\n")
+      end
+
+      def cleanup(xmldoc)
+        sourcecode_cleanup(xmldoc)
+        super
+      end
+
+      def nistvariable_insert(n)
+        acc = []
+        n.text.split(/((?<!\{)\{{3}(?!\{)|(?<!\})\}{3}(?!\}))/).each_slice(4).
+          map do |a|
+          acc << Nokogiri::XML::Text.new(a[0], n.document)
+          next unless a.size == 4
+          acc << Nokogiri::XML::Node.new("nistvariable", n)
+          acc[-1].content = a[2]
+        end
+        acc
+      end
+
+      def sourcecode_cleanup(xmldoc)
+        xmldoc.xpath("//sourcecode").each do |x|
+          x.traverse do |n|
+            next unless n.text?
+            n.replace(Nokogiri::XML::NodeSet.new(n.document, 
+                                                 nistvariable_insert(n)))
+          end
+        end
+      end
+
+      def makexml(node)
+        result = ["<?xml version='1.0' encoding='UTF-8'?>\n<nist-standard>"]
+        @draft = node.attributes.has_key?("draft")
+        result << noko { |ixml| front node, ixml }
+        result << noko { |ixml| middle node, ixml }
+        result << "</nist-standard>"
+        result = textcleanup(result.flatten * "\n")
+        ret1 = cleanup(Nokogiri::XML(result))
+        validate(ret1)
+        ret1.root.add_namespace(nil, EXAMPLE_NAMESPACE)
+        ret1
+      end
+
+      def doctype(node)
+        d = node.attr("doctype")
+        unless %w{policy-and-procedures best-practices 
+          supporting-document report legal directives proposal 
+          standard}.include? d
+          warn "#{d} is not a legal document type: reverting to 'standard'"
+          d = "standard"
+        end
+        d
+      end
+
+      def document(node)
+        init(node)
+        ret1 = makexml(node)
+        ret = ret1.to_xml(indent: 2)
+        unless node.attr("nodoc") || !node.attr("docfile")
+          filename = node.attr("docfile").gsub(/\.adoc/, ".xml").
+            gsub(%r{^.*/}, "")
+          File.open(filename, "w") { |f| f.write(ret) }
+          html_converter(node).convert filename unless node.attr("nodoc")
+          word_converter(node).convert filename unless node.attr("nodoc")
+          pdf_converter(node).convert filename unless node.attr("nodoc")
+        end
+        @files_to_delete.each { |f| FileUtils.rm f }
+        ret
+      end
+
+      def validate(doc)
+        content_validate(doc)
+        schema_validate(formattedstr_strip(doc.dup),
+                        File.join(File.dirname(__FILE__), "nist.rng"))
+      end
+
+      def sections_cleanup(x)
+        super
+        x.xpath("//*[@inline-header]").each do |h|
+          h.delete("inline-header")
+        end
+      end
+
+      def move_sections_into_preface(x, preface)
+        abstract = x.at("//abstract")
+        preface.add_child abstract.remove if abstract
+        foreword = x.at("//foreword")
+        preface.add_child foreword.remove if foreword
+        introduction = x.at("//introduction")
+        preface.add_child introduction.remove if introduction
+        x.xpath("//clause[@preface]").each do |c|
+          c.delete("preface")
+          c.name = "reviewernote" if c&.at("./title")&.text.downcase == "note to reviewers"
+          c.name = "executivesummary" if c&.at("./title")&.text.downcase == "executive summary"
+          preface.add_child c.remove
+        end
+      end
+
+      def make_preface(x, s)
+        if x.at("//foreword | //introduction | //abstract | //preface")
+          preface = s.add_previous_sibling("<preface/>").first
+          move_sections_into_preface(x, preface)
+          summ = x.at("//executivesummary") and preface.add_child summ.remove
+        end
+      end
+
+      def clause_parse(attrs, xml, node)
+        attrs[:preface] = true if node.attr("style") == "preface"
+        super
+      end
+
+      def acknowledgements_parse(attrs, xml, node)
+        xml.acknowledgements **attr_code(attrs) do |xml_section|
+          xml_section << node.content
+        end
+      end
+
+      def audience_parse(attrs, xml, node)
+        xml.audience **attr_code(attrs) do |xml_section|
+          xml_section << node.content
+        end
+      end
+
+      def conformancetesting_parse(attrs, xml, node)
+        xml.conformancetesting **attr_code(attrs) do |xml_section|
+          xml_section << node.content
+        end
+      end
+
+      def style(n, t)
+        return
+      end
+
+      def section(node)
+        a = { id: Asciidoctor::Standoc::Utils::anchor_or_uuid(node) }
+        noko do |xml|
+          case sectiontype(node)
+          when "normative references" then norm_ref_parse(a, xml, node)
+          else
+            if @term_def then term_def_subclause_parse(a, xml, node)
+            elsif @biblio then bibliography_parse(a, xml, node)
+            elsif node.attr("style") == "bibliography" && node.level == 1
+              bibliography_parse(a, xml, node)
+            elsif node.attr("style") == "abstract"
+              abstract_parse(a, xml, node)
+            elsif node.attr("style") == "appendix" && node.level == 1
+              annex_parse(a, xml, node)
+            else
+              clause_parse(a, xml, node)
+            end
+          end
+        end.join("\n")
+      end
+      def html_converter(node)
+        IsoDoc::NIST::HtmlConvert.new(html_extract_attributes(node))
+      end
+
+      def word_converter(node)
+        IsoDoc::NIST::WordConvert.new(doc_extract_attributes(node))
+      end
+
+      def pdf_converter(node)
+        IsoDoc::NIST::PdfConvert.new(html_extract_attributes(node))
+      end
+    end
+  end
+end

data/lib/asciidoctor/nist/front.rb

@@ -0,0 +1,150 @@
+require "asciidoctor"
+require "asciidoctor/standoc/converter"
+require "fileutils"
+
+module Asciidoctor
+  module NIST
+
+    # A {Converter} implementation that generates RSD output, and a document
+    # schema encapsulation of the document for validation
+    #
+    class Converter < Standoc::Converter
+
+      def metadata_author(node, xml)
+        xml.contributor do |c|
+          c.role **{ type: "author" }
+          c.organization do |a|
+            a.name "NIST"
+          end
+        end
+        personal_author(node, xml)
+      end
+
+      def personal_author(node, xml)
+        personal_editor(node, xml)
+        if node.attr("fullname") || node.attr("surname")
+          personal_author1(node, xml, "")
+        end
+        i = 2
+        while node.attr("fullname_#{i}") || node.attr("surname_#{i}")
+          personal_author1(node, xml, "_#{i}")
+          i += 1
+        end
+      end
+
+      def personal_editor(node, xml)
+        return unless node.attr("editor")
+        xml.contributor do |c|
+          c.role **{ type: "editor" }
+          c.person do |p|
+            p.name do |n|
+              n.completename node.attr("editor")
+            end
+          end
+        end
+      end
+
+      def personal_author1(node, xml, suffix)
+        xml.contributor do |c|
+          c.role **{ type: node&.attr("role#{suffix}")&.downcase || "editor" }
+          c.person do |p|
+            p.name do |n|
+              if node.attr("fullname#{suffix}")
+                n.completename node.attr("fullname#{suffix}")
+              else
+                n.forename node.attr("givenname#{suffix}")
+                n.surname node.attr("surname#{suffix}")
+              end
+            end
+          end
+        end
+      end
+
+      def metadata_publisher(node, xml)
+        xml.contributor do |c|
+          c.role **{ type: "publisher" }
+          c.organization do |a|
+            a.name "NIST"
+          end
+        end
+      end
+
+      def metadata_id(node, xml)
+        docstatus = node.attr("status")
+        dn = node.attr("docnumber")
+        if docstatus
+          abbr = IsoDoc::NIST::Metadata.new("en", "Latn", {}).
+            status_abbr(docstatus)
+          dn = "#{dn}(#{abbr})" unless abbr.empty?
+        end
+        dn and dn = "NIST " + dn
+        xml.docidentifier dn, **{type: "nist"}
+        xml.docnumber { |i| i << node.attr("docnumber") }
+      end
+
+      def metadata_committee(node, xml)
+        xml.editorialgroup do |a|
+          a.committee(node.attr("technical-committee"))
+          node.attr("subcommittee") and
+            a.subcommittee(node.attr("subcommittee"),
+                           **attr_code(type: node.attr("subcommittee-type"),
+                                       number: node.attr("subcommittee-number")))
+          (node.attr("workgroup") || node.attr("workinggroup")) and
+            a.workgroup(node.attr("workgroup") || node.attr("workinggroup"),
+                        **attr_code(type: node.attr("workgroup-type"),
+                                    number: node.attr("workgroup-number")))
+        end
+      end
+
+      def metadata_status(node, xml)
+        status = node.attr("status") || "published"
+        xml.status(**{ format: "plain" }) { |s| s << status }
+      end
+
+      def metadata_copyright(node, xml)
+        from = node.attr("copyright-year") || node.attr("copyrightyear") || Date.today.year
+        xml.copyright do |c|
+          c.from from
+          c.owner do |owner|
+            owner.organization do |o|
+              o.name "NIST"
+            end
+          end
+        end
+      end
+
+      def metadata_keywords(node, xml)
+        return unless node.attr("keywords")
+        node.attr("keywords").split(/,[ ]*/).each do |kw|
+          xml.keyword kw
+        end
+      end
+
+      def metadata_source(node, xml)
+        super
+        node.attr("email") && xml.source(node.attr("email"), type: "email")
+      end
+
+      def title(node, xml)
+        super
+        subtitle(node, xml)
+      end
+
+      def subtitle(node, xml)
+        return unless node.attr("subtitle")
+        ["en"].each do |lang|
+          at = { language: lang, format: "text/plain" }
+          xml.subtitle **attr_code(at) do |t|
+            t << asciidoc_sub(node.attr("subtitle"))
+          end
+        end
+      end
+
+      def metadata(node, xml)
+        super
+        metadata_keywords(node, xml)
+      end
+
+    end
+  end
+end

data/lib/asciidoctor/nist/isodoc.rng

@@ -0,0 +1,1063 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  instantiations of this grammar may replace leaf strings
+  with more elaborated types; e.g. title (text) replaced with
+  title-main, title-intro, title-part; type replaced with
+  enum.
+  
+  some renaming at leaf nodes is permissible
+  
+  obligations can change both from optional to mandatory,
+  and from mandatory to optional; optional elements may
+  be omitted; freely positioned alternatives may be replaced
+  with strict ordering
+  
+  DO NOT introduce a namespace here. We do not want a distinct namespace
+  for these elements, and a distinct namespace for any grammar inheriting
+  these elements; we just want one namespace for any child grammars
+  of this.
+-->
+<grammar xmlns="http://relaxng.org/ns/structure/1.0" datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes">
+  <include href="biblio.rng">
+    <define name="status">
+      <element name="status">
+        <choice>
+          <value>proposal</value>
+          <value>working_draft</value>
+          <value>committee_draft</value>
+          <value>draft_standard</value>
+          <value>final_draft</value>
+          <value>published</value>
+          <value>withdrawn</value>
+        </choice>
+      </element>
+    </define>
+  </include>
+  <start>
+    <ref name="standard-document"/>
+  </start>
+  <define name="standard-document">
+    <element name="standard-document">
+      <ref name="bibdata"/>
+      <optional>
+        <ref name="preface"/>
+      </optional>
+      <ref name="sections"/>
+      <zeroOrMore>
+        <ref name="annex"/>
+      </zeroOrMore>
+      <zeroOrMore>
+        <ref name="references"/>
+      </zeroOrMore>
+    </element>
+  </define>
+  <define name="bibdata">
+    <element name="bibdata">
+      <ref name="BibData"/>
+    </element>
+  </define>
+  <define name="preface">
+    <element name="preface">
+      <oneOrMore>
+        <ref name="content"/>
+      </oneOrMore>
+    </element>
+  </define>
+  <define name="sections">
+    <element name="sections">
+      <oneOrMore>
+        <choice>
+          <ref name="content"/>
+          <ref name="clause"/>
+          <ref name="terms"/>
+          <ref name="definitions"/>
+        </choice>
+      </oneOrMore>
+    </element>
+  </define>
+  <define name="definitions">
+    <element name="definitions">
+      <optional>
+        <attribute name="id">
+          <data type="ID"/>
+        </attribute>
+      </optional>
+      <optional>
+        <ref name="section-title"/>
+      </optional>
+      <ref name="dl"/>
+    </element>
+  </define>
+  <define name="section-title">
+    <element name="title">
+      <zeroOrMore>
+        <ref name="TextElement"/>
+      </zeroOrMore>
+    </element>
+  </define>
+  <define name="content">
+    <element name="content">
+      <ref name="Content-Section"/>
+    </element>
+  </define>
+  <define name="content-subsection">
+    <element name="clause">
+      <ref name="Content-Section"/>
+    </element>
+  </define>
+  <define name="Basic-Section">
+    <optional>
+      <attribute name="id">
+        <data type="ID"/>
+      </attribute>
+    </optional>
+    <optional>
+      <ref name="section-title"/>
+    </optional>
+    <oneOrMore>
+      <ref name="BasicBlock"/>
+    </oneOrMore>
+    <zeroOrMore>
+      <ref name="note"/>
+    </zeroOrMore>
+  </define>
+  <define name="Content-Section">
+    <optional>
+      <attribute name="id">
+        <data type="ID"/>
+      </attribute>
+    </optional>
+    <optional>
+      <ref name="section-title"/>
+    </optional>
+    <choice>
+      <group>
+        <oneOrMore>
+          <ref name="BasicBlock"/>
+        </oneOrMore>
+        <zeroOrMore>
+          <ref name="note"/>
+        </zeroOrMore>
+      </group>
+      <oneOrMore>
+        <ref name="content-subsection"/>
+      </oneOrMore>
+    </choice>
+  </define>
+  <define name="clause">
+    <element name="clause">
+      <ref name="Clause-Section"/>
+    </element>
+  </define>
+  <define name="Clause-Section">
+    <optional>
+      <attribute name="id">
+        <data type="ID"/>
+      </attribute>
+    </optional>
+    <optional>
+      <ref name="section-title"/>
+    </optional>
+    <choice>
+      <group>
+        <oneOrMore>
+          <ref name="BasicBlock"/>
+        </oneOrMore>
+        <zeroOrMore>
+          <ref name="note"/>
+        </zeroOrMore>
+      </group>
+      <oneOrMore>
+        <ref name="clause-subsection"/>
+      </oneOrMore>
+    </choice>
+  </define>
+  <define name="clause-subsection">
+    <element name="clause">
+      <ref name="Clause-Section"/>
+    </element>
+  </define>
+  <define name="annex">
+    <element name="annex">
+      <optional>
+        <attribute name="id">
+          <data type="ID"/>
+        </attribute>
+      </optional>
+      <attribute name="obligation">
+        <choice>
+          <value>normative</value>
+          <value>informative</value>
+        </choice>
+      </attribute>
+      <optional>
+        <ref name="section-title"/>
+      </optional>
+      <choice>
+        <group>
+          <oneOrMore>
+            <ref name="BasicBlock"/>
+          </oneOrMore>
+          <zeroOrMore>
+            <ref name="note"/>
+          </zeroOrMore>
+        </group>
+        <oneOrMore>
+          <ref name="clause-subsection"/>
+        </oneOrMore>
+      </choice>
+    </element>
+  </define>
+  <define name="references">
+    <element name="references">
+      <optional>
+        <attribute name="id">
+          <data type="ID"/>
+        </attribute>
+      </optional>
+      <optional>
+        <ref name="section-title"/>
+      </optional>
+      <zeroOrMore>
+        <ref name="bibitem"/>
+      </zeroOrMore>
+    </element>
+  </define>
+  <define name="terms">
+    <element name="terms">
+      <optional>
+        <attribute name="id">
+          <data type="ID"/>
+        </attribute>
+      </optional>
+      <oneOrMore>
+        <ref name="term"/>
+      </oneOrMore>
+    </element>
+  </define>
+  <define name="term">
+    <element name="term">
+      <optional>
+        <attribute name="id">
+          <data type="ID"/>
+        </attribute>
+      </optional>
+      <oneOrMore>
+        <ref name="preferred"/>
+      </oneOrMore>
+      <zeroOrMore>
+        <ref name="admitted"/>
+      </zeroOrMore>
+      <zeroOrMore>
+        <ref name="deprecates"/>
+      </zeroOrMore>
+      <optional>
+        <ref name="termdomain"/>
+      </optional>
+      <ref name="definition"/>
+      <zeroOrMore>
+        <ref name="termnote"/>
+      </zeroOrMore>
+      <zeroOrMore>
+        <ref name="termexample"/>
+      </zeroOrMore>
+      <zeroOrMore>
+        <ref name="termsource"/>
+      </zeroOrMore>
+    </element>
+  </define>
+  <define name="preferred">
+    <element name="preferred">
+      <oneOrMore>
+        <ref name="TextElement"/>
+      </oneOrMore>
+    </element>
+  </define>
+  <define name="admitted">
+    <element name="admitted">
+      <oneOrMore>
+        <ref name="TextElement"/>
+      </oneOrMore>
+    </element>
+  </define>
+  <define name="deprecates">
+    <element name="deprecates">
+      <oneOrMore>
+        <ref name="TextElement"/>
+      </oneOrMore>
+    </element>
+  </define>
+  <define name="termdomain">
+    <element name="domain">
+      <oneOrMore>
+        <ref name="TextElement"/>
+      </oneOrMore>
+    </element>
+  </define>
+  <define name="definition">
+    <element name="definition">
+      <ref name="paragraph"/>
+    </element>
+  </define>
+  <define name="termnote">
+    <element name="termnote">
+      <attribute name="id">
+        <data type="ID"/>
+      </attribute>
+      <ref name="paragraph"/>
+    </element>
+  </define>
+  <define name="termexample">
+    <element name="termexample">
+      <attribute name="id">
+        <data type="ID"/>
+      </attribute>
+      <ref name="paragraph"/>
+    </element>
+  </define>
+  <define name="termsource">
+    <element name="termsource">
+      <attribute name="status">
+        <choice>
+          <value>identical</value>
+          <value>modified</value>
+        </choice>
+      </attribute>
+      <ref name="origin"/>
+      <optional>
+        <ref name="modification"/>
+      </optional>
+    </element>
+  </define>
+  <define name="origin">
+    <element name="origin">
+      <ref name="erefType"/>
+    </element>
+  </define>
+  <define name="modification">
+    <element name="modification">
+      <ref name="paragraph"/>
+    </element>
+  </define>
+  <define name="BasicBlock">
+    <choice>
+      <ref name="paragraph-with-footnote"/>
+      <ref name="table"/>
+      <ref name="formula"/>
+      <ref name="admonition"/>
+      <ref name="ol"/>
+      <ref name="ul"/>
+      <ref name="dl"/>
+      <ref name="figure"/>
+      <ref name="quote"/>
+      <ref name="sourcecode"/>
+      <ref name="example"/>
+      <ref name="review"/>
+      <ref name="pre"/>
+    </choice>
+  </define>
+  <define name="paragraph">
+    <element name="p">
+      <ref name="ParagraphType"/>
+    </element>
+  </define>
+  <define name="Alignments">
+    <choice>
+      <value>left</value>
+      <value>right</value>
+      <value>center</value>
+      <value>justified</value>
+    </choice>
+  </define>
+  <define name="ParagraphType">
+    <attribute name="id">
+      <data type="ID"/>
+    </attribute>
+    <optional>
+      <attribute name="align">
+        <ref name="Alignments"/>
+      </attribute>
+    </optional>
+    <zeroOrMore>
+      <ref name="TextElement"/>
+    </zeroOrMore>
+    <zeroOrMore>
+      <ref name="note"/>
+    </zeroOrMore>
+  </define>
+  <define name="paragraph-with-footnote">
+    <element name="p">
+      <attribute name="id">
+        <data type="ID"/>
+      </attribute>
+      <optional>
+        <attribute name="align">
+          <ref name="Alignments"/>
+        </attribute>
+      </optional>
+      <zeroOrMore>
+        <choice>
+          <ref name="TextElement"/>
+          <ref name="fn"/>
+        </choice>
+      </zeroOrMore>
+      <zeroOrMore>
+        <ref name="note"/>
+      </zeroOrMore>
+    </element>
+  </define>
+  <define name="note">
+    <element name="note">
+      <attribute name="id">
+        <data type="ID"/>
+      </attribute>
+      <oneOrMore>
+        <ref name="paragraph"/>
+      </oneOrMore>
+    </element>
+  </define>
+  <define name="review">
+    <element name="review">
+      <attribute name="id">
+        <data type="ID"/>
+      </attribute>
+      <attribute name="reviewer"/>
+      <optional>
+        <attribute name="date">
+          <data type="dateTime"/>
+        </attribute>
+      </optional>
+      <attribute name="from">
+        <data type="IDREF"/>
+      </attribute>
+      <optional>
+        <attribute name="to">
+          <data type="IDREF"/>
+        </attribute>
+      </optional>
+      <oneOrMore>
+        <ref name="paragraph"/>
+      </oneOrMore>
+    </element>
+  </define>
+  <define name="formula">
+    <element name="formula">
+      <attribute name="id">
+        <data type="ID"/>
+      </attribute>
+      <ref name="stem"/>
+      <optional>
+        <ref name="dl"/>
+      </optional>
+      <zeroOrMore>
+        <ref name="note"/>
+      </zeroOrMore>
+    </element>
+  </define>
+  <define name="quote">
+    <element name="quote">
+      <attribute name="id">
+        <data type="ID"/>
+      </attribute>
+      <optional>
+        <attribute name="alignment">
+          <ref name="Alignments"/>
+        </attribute>
+      </optional>
+      <optional>
+        <ref name="quote-source"/>
+      </optional>
+      <optional>
+        <ref name="quote-author"/>
+      </optional>
+      <oneOrMore>
+        <ref name="paragraph-with-footnote"/>
+      </oneOrMore>
+      <zeroOrMore>
+        <ref name="note"/>
+      </zeroOrMore>
+    </element>
+  </define>
+  <define name="quote-source">
+    <element name="source">
+      <ref name="erefType"/>
+    </element>
+  </define>
+  <define name="quote-author">
+    <element name="author">
+      <text/>
+    </element>
+  </define>
+  <define name="sourcecode">
+    <element name="sourcecode">
+      <attribute name="id">
+        <data type="ID"/>
+      </attribute>
+      <optional>
+        <ref name="tname"/>
+      </optional>
+      <oneOrMore>
+        <choice>
+          <text/>
+          <ref name="callout"/>
+        </choice>
+      </oneOrMore>
+      <zeroOrMore>
+        <ref name="annotation"/>
+      </zeroOrMore>
+      <zeroOrMore>
+        <ref name="note"/>
+      </zeroOrMore>
+    </element>
+  </define>
+  <define name="pre">
+    <element name="pre">
+      <attribute name="id">
+        <data type="ID"/>
+      </attribute>
+      <optional>
+        <ref name="tname"/>
+      </optional>
+      <text/>
+      <zeroOrMore>
+        <ref name="note"/>
+      </zeroOrMore>
+    </element>
+  </define>
+  <define name="table">
+    <element name="table">
+      <attribute name="id">
+        <data type="ID"/>
+      </attribute>
+      <optional>
+        <ref name="tname"/>
+      </optional>
+      <optional>
+        <ref name="thead"/>
+      </optional>
+      <ref name="tbody"/>
+      <optional>
+        <ref name="tfoot"/>
+      </optional>
+      <zeroOrMore>
+        <ref name="table-note"/>
+      </zeroOrMore>
+      <optional>
+        <ref name="dl"/>
+      </optional>
+    </element>
+  </define>
+  <define name="tname">
+    <element name="name">
+      <text/>
+    </element>
+  </define>
+  <define name="thead">
+    <element name="thead">
+      <ref name="tr"/>
+    </element>
+  </define>
+  <define name="tfoot">
+    <element name="tfoot">
+      <ref name="tr"/>
+    </element>
+  </define>
+  <define name="tbody">
+    <element name="tbody">
+      <oneOrMore>
+        <ref name="tr"/>
+      </oneOrMore>
+    </element>
+  </define>
+  <define name="table-note">
+    <element name="note">
+      <ref name="paragraph"/>
+    </element>
+  </define>
+  <define name="tr">
+    <element name="tr">
+      <oneOrMore>
+        <choice>
+          <ref name="td"/>
+          <ref name="th"/>
+        </choice>
+      </oneOrMore>
+    </element>
+  </define>
+  <define name="td">
+    <element name="td">
+      <optional>
+        <attribute name="colspan"/>
+      </optional>
+      <optional>
+        <attribute name="rowspan"/>
+      </optional>
+      <optional>
+        <attribute name="align">
+          <choice>
+            <value>left</value>
+            <value>right</value>
+            <value>center</value>
+          </choice>
+        </attribute>
+      </optional>
+      <choice>
+        <zeroOrMore>
+          <ref name="TextElement"/>
+        </zeroOrMore>
+        <oneOrMore>
+          <ref name="paragraph-with-footnote"/>
+        </oneOrMore>
+      </choice>
+    </element>
+  </define>
+  <define name="th">
+    <element name="th">
+      <optional>
+        <attribute name="colspan"/>
+      </optional>
+      <optional>
+        <attribute name="rowspan"/>
+      </optional>
+      <optional>
+        <attribute name="align">
+          <choice>
+            <value>left</value>
+            <value>right</value>
+            <value>center</value>
+          </choice>
+        </attribute>
+      </optional>
+      <choice>
+        <zeroOrMore>
+          <ref name="TextElement"/>
+        </zeroOrMore>
+        <oneOrMore>
+          <ref name="paragraph-with-footnote"/>
+        </oneOrMore>
+      </choice>
+    </element>
+  </define>
+  <define name="example">
+    <element name="example">
+      <attribute name="id">
+        <data type="ID"/>
+      </attribute>
+      <oneOrMore>
+        <choice>
+          <ref name="formula"/>
+          <ref name="ul"/>
+          <ref name="ol"/>
+          <ref name="dl"/>
+          <ref name="quote"/>
+          <ref name="sourcecode"/>
+          <ref name="paragraph-with-footnote"/>
+        </choice>
+      </oneOrMore>
+      <zeroOrMore>
+        <ref name="note"/>
+      </zeroOrMore>
+    </element>
+  </define>
+  <define name="admonition">
+    <element name="admonition">
+      <attribute name="type">
+        <choice>
+          <value>warning</value>
+          <value>note</value>
+          <value>tip</value>
+          <value>important</value>
+          <value>caution</value>
+        </choice>
+      </attribute>
+      <attribute name="id">
+        <data type="ID"/>
+      </attribute>
+      <zeroOrMore>
+        <ref name="paragraph-with-footnote"/>
+      </zeroOrMore>
+      <zeroOrMore>
+        <ref name="note"/>
+      </zeroOrMore>
+    </element>
+  </define>
+  <define name="figure">
+    <element name="figure">
+      <attribute name="id">
+        <data type="ID"/>
+      </attribute>
+      <optional>
+        <ref name="source"/>
+      </optional>
+      <optional>
+        <ref name="tname"/>
+      </optional>
+      <choice>
+        <ref name="image"/>
+        <ref name="pre"/>
+        <zeroOrMore>
+          <ref name="figure"/>
+        </zeroOrMore>
+      </choice>
+      <zeroOrMore>
+        <ref name="fn"/>
+      </zeroOrMore>
+      <optional>
+        <ref name="dl"/>
+      </optional>
+      <zeroOrMore>
+        <ref name="note"/>
+      </zeroOrMore>
+    </element>
+  </define>
+  <define name="TextElement">
+    <choice>
+      <text/>
+      <ref name="em"/>
+      <ref name="eref"/>
+      <ref name="strong"/>
+      <ref name="stem"/>
+      <ref name="sub"/>
+      <ref name="sup"/>
+      <ref name="tt"/>
+      <ref name="keyword"/>
+      <ref name="strike"/>
+      <ref name="smallcap"/>
+      <ref name="xref"/>
+      <ref name="br"/>
+      <ref name="hyperlink"/>
+      <ref name="hr"/>
+      <ref name="pagebreak"/>
+      <ref name="bookmark"/>
+    </choice>
+  </define>
+  <define name="source">
+    <element name="source">
+      <ref name="TypedUri"/>
+    </element>
+  </define>
+  <define name="em">
+    <element name="em">
+      <text/>
+    </element>
+  </define>
+  <define name="strong">
+    <element name="strong">
+      <text/>
+    </element>
+  </define>
+  <define name="tt">
+    <element name="tt">
+      <text/>
+    </element>
+  </define>
+  <define name="keyword">
+    <element name="keyword">
+      <text/>
+    </element>
+  </define>
+  <define name="sub">
+    <element name="sub">
+      <text/>
+    </element>
+  </define>
+  <define name="sup">
+    <element name="sup">
+      <text/>
+    </element>
+  </define>
+  <define name="strike">
+    <element name="strike">
+      <text/>
+    </element>
+  </define>
+  <define name="smallcap">
+    <element name="smallcap">
+      <text/>
+    </element>
+  </define>
+  <define name="br">
+    <element name="br">
+      <empty/>
+    </element>
+  </define>
+  <define name="hr">
+    <element name="hr">
+      <empty/>
+    </element>
+  </define>
+  <define name="pagebreak">
+    <element name="pagebreak">
+      <empty/>
+    </element>
+  </define>
+  <!-- bare ID element, used for referencing arbitrary spans of text -->
+  <define name="bookmark">
+    <element name="bookmark">
+      <attribute name="id">
+        <data type="ID"/>
+      </attribute>
+      <empty/>
+    </element>
+  </define>
+  <define name="ReferenceFormat">
+    <choice>
+      <value>external</value>
+      <value>inline</value>
+      <value>footnote</value>
+      <value>callout</value>
+    </choice>
+  </define>
+  <define name="eref">
+    <element name="eref">
+      <ref name="erefType"/>
+    </element>
+  </define>
+  <define name="erefType">
+    <optional>
+      <attribute name="normative">
+        <data type="boolean"/>
+      </attribute>
+    </optional>
+    <attribute name="citeas"/>
+    <attribute name="type">
+      <ref name="ReferenceFormat"/>
+    </attribute>
+    <ref name="CitationType"/>
+    <text/>
+  </define>
+  <define name="hyperlink">
+    <element name="link">
+      <attribute name="target">
+        <data type="anyURI"/>
+      </attribute>
+      <attribute name="type">
+        <ref name="ReferenceFormat"/>
+      </attribute>
+      <text/>
+    </element>
+  </define>
+  <define name="xref">
+    <element name="xref">
+      <attribute name="target">
+        <data type="IDREF"/>
+      </attribute>
+      <attribute name="type">
+        <ref name="ReferenceFormat"/>
+      </attribute>
+      <text/>
+    </element>
+  </define>
+  <define name="fn">
+    <element name="fn">
+      <attribute name="reference"/>
+      <oneOrMore>
+        <ref name="paragraph"/>
+      </oneOrMore>
+    </element>
+  </define>
+  <!--
+    This is xref with fixed @type="footnote", and @target built in as paragraph+
+    @reference replaces ReferenceElement/text
+    so <fn reference="2"><p>This is a footnote</p></fn>
+    corresponds to 
+    <eref type="footnote" target="fn2">2</xref> <p id="fn2">This is a footnote</p>
+  -->
+  <define name="callout">
+    <element name="callout">
+      <attribute name="target">
+        <data type="IDREF"/>
+      </attribute>
+      <text/>
+    </element>
+  </define>
+  <!--
+    This is xref with fixed @type="callout"; the target by convention is in an annotation in the same source code snippet
+    so <callout target="xyz">1</callout>
+    corresponds to <xref type="callout" target="xyz">1</xref>
+  -->
+  <define name="image">
+    <element name="image">
+      <attribute name="id">
+        <data type="ID"/>
+      </attribute>
+      <optional>
+        <attribute name="src">
+          <data type="anyURI"/>
+        </attribute>
+      </optional>
+      <attribute name="imagetype">
+        <choice>
+          <value>SVG</value>
+          <value>JPEG</value>
+          <value>GIF</value>
+          <value>PNG</value>
+          <value>PDF</value>
+        </choice>
+      </attribute>
+      <optional>
+        <attribute name="width">
+          <choice>
+            <data type="int"/>
+            <value>auto</value>
+          </choice>
+        </attribute>
+      </optional>
+      <optional>
+        <attribute name="height">
+          <choice>
+            <data type="int"/>
+            <value>auto</value>
+          </choice>
+        </attribute>
+      </optional>
+    </element>
+  </define>
+  <define name="stem">
+    <element name="stem">
+      <attribute name="type">
+        <choice>
+          <value>MathML</value>
+          <value>AsciiMath</value>
+        </choice>
+      </attribute>
+      <text/>
+    </element>
+  </define>
+  <define name="annotation">
+    <element name="annotation">
+      <attribute name="id">
+        <data type="ID"/>
+      </attribute>
+      <ref name="paragraph"/>
+    </element>
+  </define>
+  <define name="ul">
+    <element name="ul">
+      <attribute name="id">
+        <data type="ID"/>
+      </attribute>
+      <oneOrMore>
+        <ref name="li"/>
+      </oneOrMore>
+      <zeroOrMore>
+        <ref name="note"/>
+      </zeroOrMore>
+    </element>
+  </define>
+  <define name="li">
+    <element name="li">
+      <optional>
+        <attribute name="id">
+          <data type="ID"/>
+        </attribute>
+      </optional>
+      <oneOrMore>
+        <ref name="paragraph-with-footnote"/>
+      </oneOrMore>
+    </element>
+  </define>
+  <define name="ol">
+    <element name="ol">
+      <attribute name="id">
+        <data type="ID"/>
+      </attribute>
+      <attribute name="type">
+        <choice>
+          <value>roman</value>
+          <value>alphabet</value>
+          <value>arabic</value>
+          <value>roman_upper</value>
+          <value>alphabet_upper</value>
+        </choice>
+      </attribute>
+      <oneOrMore>
+        <ref name="li"/>
+      </oneOrMore>
+      <zeroOrMore>
+        <ref name="note"/>
+      </zeroOrMore>
+    </element>
+  </define>
+  <define name="dl">
+    <element name="dl">
+      <attribute name="id">
+        <data type="ID"/>
+      </attribute>
+      <oneOrMore>
+        <ref name="dt"/>
+        <ref name="dd"/>
+      </oneOrMore>
+      <zeroOrMore>
+        <ref name="note"/>
+      </zeroOrMore>
+    </element>
+  </define>
+  <define name="dt">
+    <element name="dt">
+      <zeroOrMore>
+        <ref name="TextElement"/>
+      </zeroOrMore>
+    </element>
+  </define>
+  <define name="dd">
+    <element name="dd">
+      <zeroOrMore>
+        <ref name="paragraph-with-footnote"/>
+      </zeroOrMore>
+    </element>
+  </define>
+  <define name="BibData">
+    <optional>
+      <attribute name="type">
+        <ref name="BibItemType"/>
+      </attribute>
+    </optional>
+    <oneOrMore>
+      <ref name="btitle"/>
+    </oneOrMore>
+    <optional>
+      <ref name="formattedref"/>
+    </optional>
+    <zeroOrMore>
+      <ref name="bsource"/>
+    </zeroOrMore>
+    <zeroOrMore>
+      <ref name="docidentifier"/>
+    </zeroOrMore>
+    <optional>
+      <ref name="docnumber"/>
+    </optional>
+    <zeroOrMore>
+      <ref name="bdate"/>
+    </zeroOrMore>
+    <zeroOrMore>
+      <ref name="contributor"/>
+    </zeroOrMore>
+    <optional>
+      <ref name="edition"/>
+    </optional>
+    <optional>
+      <ref name="version"/>
+    </optional>
+    <zeroOrMore>
+      <ref name="biblionote"/>
+    </zeroOrMore>
+    <zeroOrMore>
+      <ref name="language"/>
+    </zeroOrMore>
+    <zeroOrMore>
+      <ref name="script"/>
+    </zeroOrMore>
+    <optional>
+      <ref name="abstract"/>
+    </optional>
+    <optional>
+      <ref name="status"/>
+    </optional>
+    <ref name="copyright"/>
+    <zeroOrMore>
+      <ref name="docrelation"/>
+    </zeroOrMore>
+  </define>
+</grammar>