metanorma-bsi 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b54389a2be552034efcc821b280f538ccc89c864463dffc9e06f78ca247211e4
+  data.tar.gz: 735cd41f8f3af50fd6c5d135c33223a6a11934f0e338d4aa32c8de083ae359bd
+SHA512:
+  metadata.gz: 047b7a5c4e731a347f448a3206ec0cab50b071c5ef1338fbd86a9b81d27ca45e6a6d887286d745efd00bbc7757102149bf59b5456f79c703679cd8522dc16900
+  data.tar.gz: 65d78de82e6bfaaca68d580675632eb18985136c9a2e35b20541201acd8441ea399959786350dc9c723c5773795b0944212f3c2c972c248359f52ed2cab15ed2

data/.gitignore

@@ -0,0 +1,6 @@
+.DS_Store
+.byebug_history
+.rspec_status
+coverage/
+
+.rubocop-https--*

data/.hound.yml

@@ -0,0 +1,3 @@
+ruby:
+  Enabled: true
+  config_file: .rubocop.yml

data/.rubocop.yml

@@ -0,0 +1,14 @@
+# This project follows the Ribose OSS style guide.
+# https://github.com/riboseinc/oss-guides
+# All project-specific additions and overrides should be specified in this file.
+inherit_from:
+  - https://raw.githubusercontent.com/riboseinc/oss-guides/master/ci/rubocop.yml
+
+# local repo-specific modifications
+
+AllCops:
+  DisplayCopNames: false
+  StyleGuideCopsOnly: false
+  TargetRubyVersion: 2.4
+Rails:
+  Enabled: true

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at ronald.tse@ribose.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

data/Gemfile

@@ -0,0 +1,7 @@
+Encoding.default_external = Encoding::UTF_8
+Encoding.default_internal = Encoding::UTF_8
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,25 @@
+BSD 2-Clause License
+
+Copyright (c) 2018, Ribose
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.adoc

@@ -0,0 +1,199 @@
+= metanorma-BSI: Metanorma processor for the British Standards Institute
+
+image:https://img.shields.io/gem/v/metanorma-bsi.svg["Gem Version", link="https://rubygems.org/gems/metanorma-bsi"]
+image:https://github.com/metanorma/metanorma-bsi/workflows/rake/badge.svg["Build Status", link="https://github.com/metanorma/metanorma-bsi/actions?workflow=rake"]
+image:https://codeclimate.com/github/metanorma/metanorma-bsi/badges/gpa.svg["Code Climate", link="https://codeclimate.com/github/metanorma/metanorma-bsi"]
+image:https://img.shields.io/github/issues-pr-raw/metanorma/metanorma-bsi.svg["Pull Requests", link="https://github.com/metanorma/metanorma-bsi/pulls"]
+image:https://img.shields.io/github/commits-since/metanorma/metanorma-bsi/latest.svg["Commits since latest",link="https://github.com/metanorma/metanorma-bsi/releases"]
+
+== Functionality
+
+This gem processes https://www.metanorma.com[Metanorma documents] following
+the Metanorma model for generating BSI standards.
+
+The gem is basically the https://github.com/metanorma/metanorma-iso gem, with some tweaking of rendering to meet the particular requirements of the BSI.
+
+It provides the following functions:
+
+. Compiles Metanorma input into the Metanorma-BSI XML format (which is identical to Metanorma-ISO, since the two standards share the same document model)
+. Validates XML output against the Metanorma-BSI document model
+** Errors are reported to console against the XML, and are intended for users to
+check that they have provided all necessary components of the
+document.
+. Metanorma-BSI XML is then converted into desired output formats.
+
+The following outputs are supported:
+
+* Primary: the canonical Metanorma-BSI XML representation (`.xml`).
+* Secondary: the Metanorma-BSI XML representation is processed to generate the following outputs
+as end deliverable BSI documents.
+** HTML (`.html`)
+** Word (`.doc`)
+
+== Structure
+
+This gem inherits from the https://github.com/metanorma/metanorma-iso
+gem, and aligns closely to it.
+
+
+=== Quickstart
+
+Please see https://www.metanorma.com for instructions to get started.
+
+If you are using a Mac, the https://github.com/metanorma/metanorma-macos-setup
+repository has instructions on setting up your machine to run Metanorma
+scripts such as this one. You need only run the following in a Terminal console:
+
+[source,console]
+----
+$ bash <(curl -s https://raw.githubusercontent.com/metanorma/metanorma-macos-setup/master/metanorma-setup)
+$ gem install metanorma-cli
+$ gem install metanorma-bsi
+----
+
+
+== Usage
+
+Using the `metanorma` CLI:
+
+[source,console]
+----
+$ metanorma --type bsi a.adoc                   # output HTML
+$ metanorma --type bsi --extensions html a.adoc # output just HTML
+$ metanorma --type bsi --extensions xml a.adoc  # output Metanorma XML
+----
+
+
+== Authoring
+
+Please refer to the Metanorma-ISO documentation for general documentation.
+
+* Metanorma-ISO general documentation: https://www.metanorma.com/software/metanorma-iso/
+
+* Metanorma-ISO guidance: https://www.metanorma.com/software/metanorma-iso/docs/guidance/
+
+
+== Documentation
+
+See https://www.metanorma.com/author/iso/[Write ISO documents with Metanorma]
+
+Extensions specific to BSI:
+
+=== Adoptiopn of standard
+
+An adopted external standard is defined as `:adopted-from:`:
+
+[source,asciidoctor]
+----
+:docidentifier: NA to BS EN 1991-1-2
+:adopted-from: EN 1991-1-2
+----
+
+
+[source,asciidoctor]
+----
+:docidentifier: BS ISO 639-2
+:adopted-from: ISO 639-2
+----
+
+
+
+=== Commentaries
+
+Commentaries are entered as notes of type `commentary`,
+with an optional `target` attribute,
+giving the anchor of the block the commentary is referencing. If no target
+is given, the commentary is assumed to be about the subclause containing it.
+
+[source,asciidoc]
+----
+[[reag]]
+=== Reagents
+
+[NOTE,type=commentary,target=reag]
+This is a commentary on the reagents
+
+[[table1]]
+.Reagents in use
+|===
+| A | B
+|===
+----
+
+____
+*7.6 Reagents*
+
+COMMENTARY ON CLAUSE 7.6
+This is a commentary on the reagents
+
+|===
+| A | B
+|===
+_Table 1: Reagents in use_
+----
+____
+
+[source,asciidoc]
+----
+[[reag]]
+=== Reagents
+
+[NOTE,type=commentary]
+This is a commentary on the reagents
+
+[[table1]]
+.Reagents in use
+|===
+| A | B
+|===
+----
+
+____
+*7.6 Reagents*
+
+COMMENTARY ON CLAUSE 7.6
+This is a commentary on the reagents
+
+|===
+| A | B
+|===
+_Table 1: Reagents in use_
+----
+____
+
+
+[source,asciidoc]
+----
+=== Reagents
+
+[NOTE,type=commentary,target=table1]
+This is a commentary on the table
+
+[[table1]]
+.Reagents in use
+|===
+| A | B
+|===
+----
+
+____
+*7.6 Reagents*
+
+COMMENTARY ON TABLE 1
+This is a commentary on the table
+
+|===
+| A | B
+|===
+_Table 1: Reagents in use_
+----
+____
+
+
+
+
+== Examples
+
+* Example documents are avalable at the https://github.com/metanorma/mn-samples-bsi[mn-samples-bsi] repository.
+* Document templates are available at the https://github.com/metanorma/mn-templates-bsi[mn-templates-bsi] repository.
+

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require 'isodoc/gem_tasks'
+
+IsoDoc::GemTasks.install
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/bin/rspec

@@ -0,0 +1,18 @@
+#!/usr/bin/env ruby
+
+# This file was generated by Bundler.
+#
+# The application 'rspec' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path(
+  "../../Gemfile", Pathname.new(__FILE__).realpath
+)
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rspec-core", "rspec")
+

data/lib/asciidoctor/bsi/basicdoc.rng

@@ -0,0 +1,1131 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<grammar xmlns="http://relaxng.org/ns/structure/1.0" datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes">
+  <include href="biblio.rng">
+    <start>
+      <ref name="document"/>
+    </start>
+  </include>
+  <define name="document">
+    <element name="document">
+      <optional>
+        <attribute name="identifier"/>
+      </optional>
+      <ref name="bibdata"/>
+      <ref name="sections"/>
+      <zeroOrMore>
+        <ref name="references"/>
+      </zeroOrMore>
+    </element>
+  </define>
+  <define name="bibdata">
+    <element name="bibdata">
+      <ref name="BibData"/>
+    </element>
+  </define>
+  <define name="sections">
+    <element name="sections">
+      <oneOrMore>
+        <ref name="section"/>
+      </oneOrMore>
+    </element>
+  </define>
+  <define name="section">
+    <element name="section">
+      <ref name="Basic-Section"/>
+      <zeroOrMore>
+        <ref name="section"/>
+      </zeroOrMore>
+    </element>
+  </define>
+  <define name="Basic-Section">
+    <optional>
+      <attribute name="id">
+        <data type="ID"/>
+      </attribute>
+    </optional>
+    <optional>
+      <attribute name="language"/>
+    </optional>
+    <optional>
+      <attribute name="script"/>
+    </optional>
+    <optional>
+      <ref name="section-title"/>
+    </optional>
+    <zeroOrMore>
+      <ref name="BasicBlock"/>
+    </zeroOrMore>
+  </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="BasicBlock"/>
+      </zeroOrMore>
+      <zeroOrMore>
+        <ref name="bibitem"/>
+      </zeroOrMore>
+    </element>
+  </define>
+  <define name="section-title">
+    <element name="title">
+      <zeroOrMore>
+        <ref name="TextElement"/>
+      </zeroOrMore>
+    </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"/>
+      <ref name="note"/>
+      <ref name="pagebreak"/>
+      <ref name="hr"/>
+      <ref name="bookmark"/>
+    </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>
+      <optional>
+        <attribute name="unnumbered">
+          <data type="boolean"/>
+        </attribute>
+      </optional>
+      <optional>
+        <attribute name="subsequence"/>
+      </optional>
+      <optional>
+        <attribute name="inequality">
+          <data type="boolean"/>
+        </attribute>
+      </optional>
+      <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>
+        <attribute name="unnumbered">
+          <data type="boolean"/>
+        </attribute>
+      </optional>
+      <optional>
+        <attribute name="subsequence"/>
+      </optional>
+      <optional>
+        <attribute name="lang"/>
+      </optional>
+      <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>
+        <attribute name="alt"/>
+      </optional>
+      <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>
+        <attribute name="unnumbered">
+          <data type="boolean"/>
+        </attribute>
+      </optional>
+      <optional>
+        <attribute name="subsequence"/>
+      </optional>
+      <optional>
+        <attribute name="alt"/>
+      </optional>
+      <optional>
+        <attribute name="summary"/>
+      </optional>
+      <optional>
+        <attribute name="uri">
+          <data type="anyURI"/>
+        </attribute>
+      </optional>
+      <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">
+      <oneOrMore>
+        <choice>
+          <ref name="PureTextElement"/>
+          <ref name="eref"/>
+          <ref name="stem"/>
+          <ref name="keyword"/>
+          <ref name="xref"/>
+          <ref name="hyperlink"/>
+        </choice>
+      </oneOrMore>
+    </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>
+      <optional>
+        <attribute name="valign">
+          <choice>
+            <value>top</value>
+            <value>middle</value>
+            <value>bottom</value>
+            <value>baseline</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>
+      <optional>
+        <attribute name="valign">
+          <choice>
+            <value>top</value>
+            <value>middle</value>
+            <value>bottom</value>
+            <value>baseline</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>
+      <optional>
+        <attribute name="unnumbered">
+          <data type="boolean"/>
+        </attribute>
+      </optional>
+      <optional>
+        <attribute name="subsequence"/>
+      </optional>
+      <optional>
+        <ref name="tname"/>
+      </optional>
+      <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">
+        <ref name="AdmonitionType"/>
+      </attribute>
+      <optional>
+        <attribute name="class"/>
+      </optional>
+      <attribute name="id">
+        <data type="ID"/>
+      </attribute>
+      <optional>
+        <attribute name="uri">
+          <data type="anyURI"/>
+        </attribute>
+      </optional>
+      <optional>
+        <ref name="tname"/>
+      </optional>
+      <zeroOrMore>
+        <ref name="paragraph-with-footnote"/>
+      </zeroOrMore>
+      <zeroOrMore>
+        <ref name="note"/>
+      </zeroOrMore>
+    </element>
+  </define>
+  <define name="AdmonitionType">
+    <choice>
+      <value>warning</value>
+      <value>note</value>
+      <value>tip</value>
+      <value>important</value>
+      <value>caution</value>
+      <value>statement</value>
+    </choice>
+  </define>
+  <define name="figure">
+    <element name="figure">
+      <attribute name="id">
+        <data type="ID"/>
+      </attribute>
+      <optional>
+        <attribute name="unnumbered">
+          <data type="boolean"/>
+        </attribute>
+      </optional>
+      <optional>
+        <attribute name="subsequence"/>
+      </optional>
+      <optional>
+        <attribute name="class"/>
+      </optional>
+      <optional>
+        <ref name="source"/>
+      </optional>
+      <optional>
+        <ref name="tname"/>
+      </optional>
+      <choice>
+        <ref name="image"/>
+        <ref name="video"/>
+        <ref name="audio"/>
+        <ref name="pre"/>
+        <oneOrMore>
+          <ref name="paragraph-with-footnote"/>
+        </oneOrMore>
+        <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="underline"/>
+      <ref name="keyword"/>
+      <ref name="ruby"/>
+      <ref name="strike"/>
+      <ref name="smallcap"/>
+      <ref name="xref"/>
+      <ref name="br"/>
+      <ref name="hyperlink"/>
+      <ref name="hr"/>
+      <ref name="pagebreak"/>
+      <ref name="bookmark"/>
+      <ref name="image"/>
+      <ref name="index"/>
+      <ref name="index-xref"/>
+    </choice>
+  </define>
+  <define name="PureTextElement">
+    <choice>
+      <text/>
+      <ref name="em"/>
+      <ref name="strong"/>
+      <ref name="sub"/>
+      <ref name="sup"/>
+      <ref name="tt"/>
+      <ref name="underline"/>
+      <ref name="strike"/>
+      <ref name="smallcap"/>
+      <ref name="br"/>
+    </choice>
+  </define>
+  <define name="source">
+    <element name="source">
+      <ref name="TypedUri"/>
+    </element>
+  </define>
+  <define name="em">
+    <element name="em">
+      <zeroOrMore>
+        <choice>
+          <ref name="PureTextElement"/>
+          <ref name="stem"/>
+        </choice>
+      </zeroOrMore>
+    </element>
+  </define>
+  <define name="strong">
+    <element name="strong">
+      <zeroOrMore>
+        <choice>
+          <ref name="PureTextElement"/>
+          <ref name="stem"/>
+        </choice>
+      </zeroOrMore>
+    </element>
+  </define>
+  <define name="tt">
+    <element name="tt">
+      <zeroOrMore>
+        <ref name="PureTextElement"/>
+      </zeroOrMore>
+    </element>
+  </define>
+  <define name="keyword">
+    <element name="keyword">
+      <zeroOrMore>
+        <ref name="PureTextElement"/>
+      </zeroOrMore>
+    </element>
+  </define>
+  <define name="sub">
+    <element name="sub">
+      <zeroOrMore>
+        <ref name="PureTextElement"/>
+      </zeroOrMore>
+    </element>
+  </define>
+  <define name="sup">
+    <element name="sup">
+      <zeroOrMore>
+        <ref name="PureTextElement"/>
+      </zeroOrMore>
+    </element>
+  </define>
+  <define name="strike">
+    <element name="strike">
+      <zeroOrMore>
+        <ref name="PureTextElement"/>
+      </zeroOrMore>
+    </element>
+  </define>
+  <define name="underline">
+    <element name="underline">
+      <zeroOrMore>
+        <ref name="PureTextElement"/>
+      </zeroOrMore>
+    </element>
+  </define>
+  <define name="smallcap">
+    <element name="smallcap">
+      <zeroOrMore>
+        <ref name="PureTextElement"/>
+      </zeroOrMore>
+    </element>
+  </define>
+  <define name="ruby">
+    <element name="ruby">
+      <zeroOrMore>
+        <choice>
+          <ref name="PureTextElement"/>
+          <ref name="rp"/>
+          <ref name="rt"/>
+        </choice>
+      </zeroOrMore>
+    </element>
+  </define>
+  <define name="rp">
+    <element name="rp">
+      <zeroOrMore>
+        <ref name="PureTextElement"/>
+      </zeroOrMore>
+    </element>
+  </define>
+  <define name="rt">
+    <element name="rt">
+      <zeroOrMore>
+        <ref name="PureTextElement"/>
+      </zeroOrMore>
+    </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>
+  <define name="index">
+    <element name="index">
+      <optional>
+        <attribute name="to">
+          <data type="IDREF"/>
+        </attribute>
+      </optional>
+      <element name="primary">
+        <oneOrMore>
+          <ref name="PureTextElement"/>
+        </oneOrMore>
+      </element>
+      <optional>
+        <element name="secondary">
+          <oneOrMore>
+            <ref name="PureTextElement"/>
+          </oneOrMore>
+        </element>
+      </optional>
+      <optional>
+        <element name="tertiary">
+          <oneOrMore>
+            <ref name="PureTextElement"/>
+          </oneOrMore>
+        </element>
+      </optional>
+    </element>
+  </define>
+  <define name="index-xref">
+    <element name="index-xref">
+      <attribute name="also">
+        <data type="boolean"/>
+      </attribute>
+      <element name="primary">
+        <oneOrMore>
+          <ref name="PureTextElement"/>
+        </oneOrMore>
+      </element>
+      <optional>
+        <element name="secondary">
+          <oneOrMore>
+            <ref name="PureTextElement"/>
+          </oneOrMore>
+        </element>
+      </optional>
+      <optional>
+        <element name="tertiary">
+          <oneOrMore>
+            <ref name="PureTextElement"/>
+          </oneOrMore>
+        </element>
+      </optional>
+      <element name="target">
+        <oneOrMore>
+          <ref name="PureTextElement"/>
+        </oneOrMore>
+      </element>
+    </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>
+    <optional>
+      <attribute name="alt"/>
+    </optional>
+    <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>
+      <optional>
+        <attribute name="alt"/>
+      </optional>
+      <text/>
+    </element>
+  </define>
+  <define name="xref">
+    <element name="xref">
+      <attribute name="target">
+        <data type="IDREF"/>
+      </attribute>
+      <attribute name="type">
+        <ref name="ReferenceFormat"/>
+      </attribute>
+      <optional>
+        <attribute name="alt"/>
+      </optional>
+      <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>
+      <attribute name="src">
+        <data type="anyURI"/>
+      </attribute>
+      <attribute name="mimetype"/>
+      <optional>
+        <attribute name="filename"/>
+      </optional>
+      <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>
+      <optional>
+        <attribute name="alt"/>
+      </optional>
+      <optional>
+        <attribute name="title"/>
+      </optional>
+      <optional>
+        <attribute name="longdesc">
+          <data type="anyURI"/>
+        </attribute>
+      </optional>
+    </element>
+  </define>
+  <define name="video">
+    <element name="video">
+      <attribute name="id">
+        <data type="ID"/>
+      </attribute>
+      <attribute name="src">
+        <data type="anyURI"/>
+      </attribute>
+      <attribute name="mimetype"/>
+      <optional>
+        <attribute name="filename"/>
+      </optional>
+      <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>
+      <optional>
+        <attribute name="alt"/>
+      </optional>
+      <optional>
+        <attribute name="title"/>
+      </optional>
+      <optional>
+        <attribute name="longdesc">
+          <data type="anyURI"/>
+        </attribute>
+      </optional>
+      <zeroOrMore>
+        <ref name="altsource"/>
+      </zeroOrMore>
+    </element>
+  </define>
+  <define name="audio">
+    <element name="audio">
+      <attribute name="id">
+        <data type="ID"/>
+      </attribute>
+      <attribute name="src">
+        <data type="anyURI"/>
+      </attribute>
+      <attribute name="mimetype"/>
+      <optional>
+        <attribute name="filename"/>
+      </optional>
+      <optional>
+        <attribute name="alt"/>
+      </optional>
+      <optional>
+        <attribute name="title"/>
+      </optional>
+      <optional>
+        <attribute name="longdesc">
+          <data type="anyURI"/>
+        </attribute>
+      </optional>
+      <zeroOrMore>
+        <ref name="altsource"/>
+      </zeroOrMore>
+    </element>
+  </define>
+  <define name="altsource">
+    <element name="altsource">
+      <attribute name="src">
+        <data type="anyURI"/>
+      </attribute>
+      <attribute name="mimetype"/>
+      <optional>
+        <attribute name="filename"/>
+      </optional>
+    </element>
+  </define>
+  <define name="stem">
+    <element name="stem">
+      <attribute name="type">
+        <choice>
+          <value>MathML</value>
+          <value>AsciiMath</value>
+        </choice>
+      </attribute>
+      <oneOrMore>
+        <choice>
+          <text/>
+          <ref name="AnyElement"/>
+        </choice>
+      </oneOrMore>
+    </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>
+      <optional>
+        <attribute name="start"/>
+      </optional>
+      <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="ext">
+    <element name="ext">
+      <ref name="BibDataExtensionType"/>
+    </element>
+  </define>
+  <define name="BibDataExtensionType">
+    <ref name="doctype"/>
+  </define>
+  <define name="doctype">
+    <element name="doctype">
+      <ref name="DocumentType"/>
+    </element>
+  </define>
+  <define name="DocumentType">
+    <value>document</value>
+  </define>
+  <define name="BibData">
+    <ref name="BibliographicItem"/>
+    <optional>
+      <ref name="ext"/>
+    </optional>
+  </define>
+</grammar>