metanorma-ogc 0.0.2

data/lib/asciidoctor/ogc/converter.rb

@@ -0,0 +1,253 @@
+require "asciidoctor"
+require "asciidoctor/standoc/converter"
+require "fileutils"
+require_relative "front"
+
+module Asciidoctor
+  module Ogc
+
+    # A {Converter} implementation that generates RSD output, and a document
+    # schema encapsulation of the document for validation
+    #
+    class Converter < Standoc::Converter
+
+      register_for "ogc"
+
+      # ignore, we generate ToC outside of asciidoctor
+      def toc(value)
+      end
+
+      def title_validate(root)
+        nil
+      end
+
+      def makexml(node)
+        result = ["<?xml version='1.0' encoding='UTF-8'?>\n<ogc-standard>"]
+        @draft = node.attributes.has_key?("draft")
+        result << noko { |ixml| front node, ixml }
+        result << noko { |ixml| middle node, ixml }
+        result << "</ogc-standard>"
+        result = textcleanup(result.flatten * "\n")
+        ret1 = cleanup(Nokogiri::XML(result))
+        validate(ret1)
+        ret1.root.add_namespace(nil, Metanorma::Ogc::DOCUMENT_NAMESPACE)
+        ret1
+      end
+
+      def doctype(node)
+        d = node.attr("doctype")
+        unless %w{standard standard-with-suite abstract-specification
+        community-standard profile best-practice 
+        engineering-report discussion-paper reference-model user-guide
+        policy guide amendment technical-corrigendum administrative}.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__), "ogc.rng"))
+      end
+
+      def section_validate(doc)
+        sections_sequence_validate(doc.root)
+      end
+
+      STANDARDTYPE = %w{standard standard-with-suite abstract-specification
+      community-standard profile}.freeze
+
+      # spec of permissible section sequence
+      # we skip normative references, it goes to end of list
+      SEQ = 
+        [
+          {
+            msg: "Prefatory material must be followed by (clause) Scope",
+            val: [{ tag: "clause", title: "Scope" }],
+          },
+          {
+            msg: "Scope must be followed by Conformance",
+            val: [{ tag: "clause", title: "Conformance" }],
+          },
+          {
+            msg: "Normative References must be followed by "\
+            "Terms and Definitions",
+            val: [
+              { tag: "terms", title: "Terms and definitions" },
+              { tag: "clause", title: "Terms and definitions" },
+              {
+                tag: "terms",
+                title: "Terms, definitions, symbols and abbreviated terms",
+              },
+              {
+                tag: "clause",
+                title: "Terms, definitions, symbols and abbreviated terms",
+              },
+            ],
+          },
+      ].freeze
+
+      def seqcheck(names, msg, accepted)
+        n = names.shift
+        unless accepted.include? n
+          warn "OGC style: #{msg}"
+          names = []
+        end
+        names
+      end
+
+      def sections_sequence_validate(root)
+        return unless STANDARDTYPE.include? root&.at("//bibdata/@type")&.text
+        f = root.at("//sections").elements
+        names = f.map { |s| { tag: s.name, title: s&.at("./title")&.text } }
+        names = seqcheck(names, SEQ[0][:msg], SEQ[0][:val]) || return
+        names = seqcheck(names, SEQ[1][:msg], SEQ[1][:val]) || return
+        names = seqcheck(names, SEQ[2][:msg], SEQ[2][:val]) || return
+        n = names.shift
+        if n == { tag: "definitions", title: nil }
+          n = names.shift
+        end
+        unless n
+          warn "OGC style: Document must contain at least one clause"
+          return
+        end
+        root.at("//references | //clause[descendant::references][not(parent::clause)]") or
+          seqcheck([{tag: "clause"}], 
+                   "Normative References are mandatory", [{tag: "references"}])
+      end
+
+      def sections_cleanup(x)
+        super
+        x.xpath("//*[@inline-header]").each do |h|
+          h.delete("inline-header")
+        end
+      end
+
+      def make_preface(x, s)
+        super
+        if x.at("//submitters")
+          preface = s.at("//preface") || s.add_previous_sibling("<preface/>").first
+          submitters = x.at("//submitters").remove
+          preface.add_child submitters.remove
+        end
+      end
+
+      def clause_parse(attrs, xml, node)
+        clausetype = node&.attr("heading")&.downcase || node.title.downcase
+        if clausetype == "submitters" then submitters_parse(attrs, xml, node)
+        else
+          super
+        end
+      end
+
+      def bibliography_parse(attrs, xml, node)
+        clausetype = node&.attr("heading")&.downcase || node.title.downcase
+        if clausetype == "references" then norm_ref_parse(attrs, xml, node) 
+        else
+          super
+        end
+      end
+
+      def submitters_parse(attrs, xml, node)
+        xml.submitters **attr_code(attrs) do |xml_section|
+          xml_section << node.content
+        end
+      end
+
+      def example(node)
+        return term_example(node) if in_terms?
+        noko do |xml|
+          xml.example **id_attr(node) do |ex|
+            figure_title(node, ex)
+            wrap_in_para(node, ex)
+          end
+        end.join("\n")
+      end
+
+      def style(n, t)
+        return
+      end
+
+      def termdef_boilerplate_cleanup(xmldoc)
+        return
+      end
+
+      def cleanup(xmldoc)
+        recommendation_cleanup(xmldoc)
+        requirement_cleanup(xmldoc)
+        permission_cleanup(xmldoc)
+        super
+      end
+
+      def recommendation_cleanup(xmldoc)
+        xmldoc.xpath("//table").each do |t|
+          td = t&.at("./tbody/tr/td[1]")&.text
+          /^\s*(Recommendation( \d+)?)\s*$/.match td or next
+          body = t&.at("./tbody/tr/td[2]") or next
+          t.name = "recommendation"
+          t.children = body&.children
+          label = t&.at("./p")&.remove or next
+          label.name = "name"
+          t.prepend_child label
+        end
+      end
+
+      def requirement_cleanup(xmldoc)
+        xmldoc.xpath("//table").each do |t|
+          td = t&.at("./tbody/tr/td[1]")&.text
+          /^\s*(Requirement( \d+)?)\s*$/.match td or next
+          body = t&.at("./tbody/tr/td[2]") or next
+          t.name = "requirement"
+          t.children = body&.children
+          label = t&.at("./p")&.remove or next
+          label.name = "name"
+          t.prepend_child label
+        end
+      end
+
+      def permission_cleanup(xmldoc)
+        xmldoc.xpath("//table").each do |t|
+          td = t&.at("./tbody/tr/td[1]")&.text
+          /^\s*(Permission( \d+)?)\s*/.match td or next
+          body = t&.at("./tbody/tr/td[2]") or next
+          t.name = "permission"
+          t.children = body&.children
+          label = t&.at("./p")&.remove or next
+          label.name = "name"
+          t.prepend_child label
+        end
+      end
+
+
+      def html_converter(node)
+        IsoDoc::Ogc::HtmlConvert.new(html_extract_attributes(node))
+      end
+
+      def pdf_converter(node)
+        IsoDoc::Ogc::PdfConvert.new(html_extract_attributes(node))
+      end
+
+      def word_converter(node)
+        IsoDoc::Ogc::WordConvert.new(doc_extract_attributes(node))
+      end
+    end
+  end
+end

data/lib/asciidoctor/ogc/front.rb

@@ -0,0 +1,163 @@
+require "asciidoctor"
+require "asciidoctor/standoc/converter"
+require "fileutils"
+
+module Asciidoctor
+  module Ogc
+
+    # 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)
+        corporate_author(node, xml)
+        personal_author(node, xml)
+      end
+
+      def corporate_author(node, xml)
+        return unless node.attr("submitting-organizations")
+        node.attr("submitting-organizations").split(/;[ ]*/).each do |org|
+          xml.contributor do |c|
+            c.role **{ type: "author" }
+            c.organization do |a|
+              a.name org
+            end
+          end
+        end
+      end
+
+      def personal_author(node, xml)
+        ogc_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 ogc_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 Metanorma::Ogc::ORGANIZATION_NAME_SHORT
+          end
+        end
+      end
+
+      def metadata_committee(node, xml)
+        xml.editorialgroup do |a|
+          a.committee(node.attr("committee") || "technical")
+          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_id(node, xml)
+        node.attr("external-id") and
+          xml.docidentifier node.attr("external-id"), **{ type: "ogc-external" }
+        node.attr("referenceurlid") and
+          xml.docidentifier externalurl(node), **{ type: "ogc-external" }
+        docnumber = node.attr("docnumber") || node.attr("docreference")
+        if docnumber
+          xml.docidentifier docnumber, **{ type: "ogc-internal" }
+          xml.docnumber docnumber
+        end
+      end
+
+      def externalurl(node)
+        if node.attr("doctype") == "engineering-report"
+          "http://www.opengis.net/doc/PER/t14-#{node.attr('referenceurlid')}"
+        else
+          node.attr('referenceurlid')
+        end
+      end
+
+      def metadata_source(node, xml)
+        super
+        node.attr("previous-uri") && xml.source(node.attr("previous-uri"), type: "previous")
+      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 Metanorma::Ogc::ORGANIZATION_NAME_SHORT
+            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_date(node, xml)
+        super
+        ogc_date(node, xml, "submissiondate", "received" )
+        ogc_date(node, xml, "publicationdate", "published" )
+        ogc_date(node, xml, "approvaldate", "issued" )
+      end
+
+      def ogc_date(node, xml, ogcname, metanormaname)
+        if node.attr(ogcname)
+          xml.date **{ type: metanormaname } do |d|
+            d.on node.attr(ogcname)
+          end
+        end
+      end
+
+      def metadata(node, xml)
+        super
+        metadata_keywords(node, xml)
+      end
+    end
+  end
+end

data/lib/asciidoctor/ogc/isodoc.rng

@@ -0,0 +1,1091 @@
+<?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="version"/>
+      </optional>
+      <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="version">
+    <element name="version">
+      <optional>
+        <ref name="vedition"/>
+      </optional>
+      <optional>
+        <ref name="revision-date"/>
+      </optional>
+      <zeroOrMore>
+        <ref name="draft"/>
+      </zeroOrMore>
+    </element>
+  </define>
+  <define name="vedition">
+    <element name="edition">
+      <data type="int"/>
+    </element>
+  </define>
+  <define name="revision-date">
+    <element name="revision-date">
+      <data type="date"/>
+    </element>
+  </define>
+  <define name="draft">
+    <element name="draft">
+      <text/>
+    </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>
+    <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>