metanorma-unece 0.0.2

data/.rubocop.yml

@@ -0,0 +1,15 @@
+# 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:
+  # Thoughtbot's style guide from: https://github.com/thoughtbot/guides
+  - ".rubocop.tb.yml"
+  # Overrides from Ribose
+  - ".rubocop.ribose.yml"
+AllCops:
+  DisplayCopNames: false
+  StyleGuideCopsOnly: false
+  TargetRubyVersion: 2.5
+Rails:
+  Enabled: true

data/.travis.yml

@@ -0,0 +1,21 @@
+dist: trusty
+sudo: false
+language: ruby
+rvm:
+  - 2.5
+  - 2.4
+  - 2.3
+  - ruby-head
+before_install:
+  - gem install bundler -v 1.16.1
+  - unset _JAVA_OPTIONS
+  - wget "http://downloads.sourceforge.net/project/plantuml/plantuml.jar?r=&ts=1424308684&use_mirror=jaist" -O plantuml.jar
+  - sudo mkdir -p /opt/plantuml
+  - sudo cp plantuml.jar /opt/plantuml
+  - echo "#! /bin/sh" > plantuml.sh
+  - echo 'exec java -jar /opt/plantuml/plantuml.jar "$@"' >> plantuml.sh
+  - sudo install -m 755 -D plantuml.sh /usr/bin/plantuml
+  - plantuml -version
+matrix:
+  allow_failures:
+    - rvm: ruby-head

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,4 @@
+source "https://rubygems.org"
+git_source(:github) {|repo| "https://github.com/#{repo}" }
+
+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,202 @@
+= Metanorma processor for UNECE documents
+
+image:https://img.shields.io/gem/v/metanorma-unece.svg["Gem Version", link="https://rubygems.org/gems/metanorma-unece"]
+image:https://img.shields.io/travis/riboseinc/metanorma-unece/master.svg["Build Status", link="https://travis-ci.org/riboseinc/metanorma-unece"]
+image:https://codeclimate.com/github/riboseinc/metanorma-unece/badges/gpa.svg["Code Climate", link="https://codeclimate.com/github/riboseinc/metanorma-unece"]
+
+WARNING: This gem is still under development.
+
+
+== Functionality
+
+This gem processes http://asciidoctor.org/[Asciidoctor] documents following
+a template for generating UNECE International Standards.
+
+The gem currently inherits from the https://github.com/riboseinc/metanorma-standoc[Metanorma-Standoc]
+gem, and aligns closely to it. Refer to the ISO gem documentation
+for guidance, including https://github.com/riboseinc/metanorma-iso/wiki/Guidance-for-authoring[the Authoring Guide].
+
+The following outputs are generated.
+
+* (Optional) An HTML preview generated directly from the Asciidoctor document,
+using native AsciiDoc formatting.
+** http://asciimath.org[AsciiMathML] is to be used for mathematical formatting.
+The gem uses the https://github.com/asciidoctor/asciimath[Ruby AsciiMath parser],
+which is syntactically stricter than the common MathJax processor;
+if you do not get expected results, try bracketing terms your in AsciiMathML
+expressions.
+
+* an XML representation of the document, intended as a document model for UNECE
+International Standards.
+
+* The XML representation is processed in turn to generate the following outputs
+as end deliverable UNECE standard drafts.
+** HTML
+** Word
+
+This AsciiDoc syntax for writing UNECE standards is hereby named "AsciiUNECE".
+
+== Usage
+
+The preferred way to invoke this gem is via the `metanorma` script:
+
+[source,console]
+----
+$ metanorma --type unece a.adoc                   # output HTML and PDF
+$ metanorma --type unece --extensions html a.adoc # output just HTML
+$ metanorma --type unece --extensions pdf a.adoc  # output just PDF
+$ metanorma --type unece --extensions xml a.adoc  # output UNECE XML
+----
+
+The gem translates the document into UNECE XML format, and then
+validates its output against the UNECE XML 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.
+
+The gem then converts the XML into HTML and PDF.
+
+////
+The gem can also be invoked directly within asciidoctor, though this is deprecated:
+
+[source,console]
+----
+$ asciidoctor -b unece -r 'metanorma-unece' a.adoc
+----
+////
+
+== Installation
+
+=== Quick start
+
+https://www.metanorma.com/overview/getting-started/
+
+=== macOS
+
+If you are using macOS, the https://github.com/riboseinc/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/riboseinc/metanorma-macos-setup/master/metanorma-setup)
+$ gem install metanorma-unece
+----
+
+=== PDF output
+
+PDF output is generated by printing the HTML output as PDF. This is done
+within the gem, using
+https://developers.google.com/web/updates/2017/04/headless-chrome[Headless Chrome],
+via the https://github.com/GoogleChrome/puppeteer[Puppeteer] Node library.
+
+To get the PDF output working, do the following:
+
+* Install Node, with at least version 7.6.0: https://nodejs.org/en/download/,
+https://nodejs.org/en/download/package-manager/ . (For Mac, `brew install node`)
+* Install npm: https://docs.npmjs.com/getting-started/installing-node
+* Install puppeteer: `npm install -g --save --save-exact puppeteer`
+
+NOTE: The https://github.com/riboseinc/metanorma-macos-setup script already
+includes Puppeteer installation.
+
+
+== Approach
+
+=== Document model
+
+The UNECE Standard Document model is an instance of the
+https://github.com/riboseinc/metanorma-model-standoc[StandardDocument model].
+
+The UNECE format ("UNECE XML") intends to introduce rigor into the UNECE
+standards authoring process, and is prescribed in a separate document.
+
+=== Asciidoctor
+
+Asciidoctor has been selected as the authoring tool to generate the document
+model representation of UNECE standards. It is a document formatting tool like
+Markdown and DocBook, which combines the relative ease of use of the former
+(using relatively lightweight markup), and the rigor and expressively of the
+latter (it has a well-defined syntax, and was in fact initially developed as a
+DocBook document authoring tool). Asciidoctor has built-in capability to output
+Text, DocBook and HTML; so it can be used to preview the file as it is being
+authored.
+
+Generating documents via a document model substantially automated formatting
+associated with the document, including automating numbering of headings, figures,
+tables etc, and automatically generating references and citations.
+
+== Document Attributes
+
+=== Common attributes
+
+The gem relies on Asciidoctor document attributes to provide necessary
+metadata about the document. These include:
+
+`:edition:`:: The document edition
+
+`:revdate:`:: The date the document was last updated
+
+`:copyright-year:`:: The year which will be claimed as when the copyright for
+the document was issued
+
+`:title:`:: The main component of the English title of the document
+(mandatory). (The first line of the AsciiDoc document, which contains the title
+introduced with `=`, is ignored)
+
+`:doctype:`:: The document type (see _UNECE deliverables: The different types of
+UNECE publications_) (mandatory). Note that the document types are reflected in the
+document identifier. The permitted types are:
++
+--
+recommendation:: UNECE Recommendation
+plenary:: UNECE Plenary document
+--
+
+`:status:``:: The document status. The permitted types are: `proposal`,
+`working-draft`, `committee-draft`, `draft-standard`, `final-draft`,
+`published`, `withdrawn`.
+
+`:committee:`:: The name of the relevant UNECE committee, for example,
+  `United Nations Centre for Trade Facilitation and Electronic Business (UN/CEFACT)` (mandatory)
+
+`:language:` :: The language of the document (only `en` for now)  (mandatory)
+`:script:` :: The language of the document (only `Latn` for now)  (mandatory)
+
+NOTE: The attribute `:draft:`, if present, includes review notes in the XML output;
+these are otherwise suppressed.
+
+
+=== Recommendation specific attributes
+
+`:docnumber:`:: The document number if the document is a Recommendation. e.g. `42` for Recommendation 42, which happens to be the ultimate answer. (mandatory for Recommendation)
+
+
+=== Plenary document specific attributes
+
+`:session-date:`:: Date of the session where this document will be discussed. e.g. `Geneva, 30 April – 1 May 2018`
+
+`:agenda-item:`:: Number of the agenda item this document belongs to. e.g. `Item 6 of the provisional agenda`
+
+`:collaborator:`:: Collaborator of this document, if any. e.g. `World Economic Forum`
+
+`:agenda-id:`:: The unique ID number of this agenda item. e.g. `ECE/TRADE/C/CEFACT/2018/6`
+
+`:distribution:`:: Extent of distribution allowed. e.g. `General`
+
+
+== Data Models
+
+The UNECE Standard Document format is an instance of the
+https://github.com/riboseinc/metanorma-model-standoc[StandardDocument model]. Details of
+this general model can be found on its page.
+
+Details of the UNECE modifications to this general model can be found in the
+https://github.com/riboseinc/metanorma-model-unece[UNECE model]
+repository.
+
+== Examples
+
+* link:spec/examples/plenary.adoc[] is the source file for the "`ECE/TRADE/C/CEFACT/2018/6`" plenary document.
+* link:spec/examples/rec42.adoc[] is the source file for Recommendation 42.
+* link:spec/examples/rfc6350.adoc[] is the UNECE version of https://tools.ietf.org/html/rfc6350[RFC 6350].

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "metanorma/unece"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/rspec

@@ -0,0 +1,17 @@
+#!/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/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/asciidoctor/unece.rb

@@ -0,0 +1,7 @@
+require "asciidoctor/unece/converter"
+
+module Asciidoctor
+  module Unece
+
+  end
+end

data/lib/asciidoctor/unece/biblio.rng

@@ -0,0 +1,880 @@
+<?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:a="http://relaxng.org/ns/compatibility/annotations/1.0" xmlns="http://relaxng.org/ns/structure/1.0" datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes">
+  <define name="status">
+    <element name="status">
+      <ref name="LocalizedString"/>
+    </element>
+  </define>
+  <define name="language">
+    <element name="language">
+      <text/>
+    </element>
+  </define>
+  <define name="script">
+    <a:documentation>ISO-639</a:documentation>
+    <element name="script">
+      <text/>
+    </element>
+  </define>
+  <define name="edition">
+    <a:documentation>ISO-15924: Latn</a:documentation>
+    <element name="edition">
+      <text/>
+    </element>
+  </define>
+  <define name="LocalizedString">
+    <optional>
+      <!-- multiple languages and scripts possible: comma delimit them if so -->
+      <attribute name="language"/>
+    </optional>
+    <optional>
+      <attribute name="script"/>
+    </optional>
+    <text/>
+  </define>
+  <!--
+    Unlike UML, change type to format: type is overloaded
+    Would be need if plain were default value and could omit the attribute
+    Added LocalizedStringOrXsAny
+  -->
+  <define name="FormattedString">
+    <optional>
+      <!-- attribute format { ( "plain" | "html" | "docbook" | "tei" | "asciidoc" | "markdown" ) }?, -->
+      <attribute name="format">
+        <choice>
+          <value>text/plain</value>
+          <value>text/html</value>
+          <value>application/docbook+xml</value>
+          <value>application/tei+xml</value>
+          <value>text/x-asciidoc</value>
+          <value>text/markdown</value>
+          <value>application/x-isodoc+xml</value>
+          <text/>
+        </choice>
+      </attribute>
+    </optional>
+    <ref name="LocalizedStringOrXsAny"/>
+  </define>
+  <define name="LocalizedStringOrXsAny">
+    <optional>
+      <!-- multiple languages and scripts possible: comma delimit them if so -->
+      <attribute name="language"/>
+    </optional>
+    <optional>
+      <attribute name="script"/>
+    </optional>
+    <oneOrMore>
+      <choice>
+        <text/>
+        <ref name="AnyElement"/>
+      </choice>
+    </oneOrMore>
+  </define>
+  <define name="contributor">
+    <element name="contributor">
+      <zeroOrMore>
+        <ref name="role"/>
+      </zeroOrMore>
+      <ref name="ContributorInfo"/>
+    </element>
+  </define>
+  <define name="role">
+    <element name="role">
+      <optional>
+        <attribute name="type">
+          <choice>
+            <value>author</value>
+            <value>performer</value>
+            <value>publisher</value>
+            <value>editor</value>
+            <value>adapter</value>
+            <value>translator</value>
+            <value>distributor</value>
+          </choice>
+        </attribute>
+      </optional>
+      <zeroOrMore>
+        <ref name="roledescription"/>
+      </zeroOrMore>
+    </element>
+  </define>
+  <define name="ContributorInfo">
+    <choice>
+      <ref name="person"/>
+      <ref name="organization"/>
+    </choice>
+  </define>
+  <define name="roledescription">
+    <element name="description">
+      <ref name="FormattedString"/>
+    </element>
+  </define>
+  <define name="person">
+    <element name="person">
+      <optional>
+        <ref name="fullname"/>
+      </optional>
+      <zeroOrMore>
+        <ref name="affiliation"/>
+      </zeroOrMore>
+      <zeroOrMore>
+        <ref name="person-identifier"/>
+      </zeroOrMore>
+      <zeroOrMore>
+        <ref name="contact"/>
+      </zeroOrMore>
+      <optional>
+        <ref name="uri"/>
+      </optional>
+    </element>
+  </define>
+  <define name="fullname">
+    <element name="name">
+      <choice>
+        <group>
+          <zeroOrMore>
+            <ref name="prefix"/>
+          </zeroOrMore>
+          <zeroOrMore>
+            <ref name="forename"/>
+          </zeroOrMore>
+          <zeroOrMore>
+            <ref name="initial"/>
+          </zeroOrMore>
+          <ref name="surname"/>
+          <zeroOrMore>
+            <ref name="addition"/>
+          </zeroOrMore>
+        </group>
+        <ref name="completeName"/>
+      </choice>
+      <zeroOrMore>
+        <ref name="biblionote"/>
+      </zeroOrMore>
+    </element>
+  </define>
+  <define name="prefix">
+    <element name="prefix">
+      <ref name="LocalizedString"/>
+    </element>
+  </define>
+  <define name="initial">
+    <element name="initial">
+      <ref name="LocalizedString"/>
+    </element>
+  </define>
+  <define name="addition">
+    <element name="addition">
+      <ref name="LocalizedString"/>
+    </element>
+  </define>
+  <define name="surname">
+    <element name="surname">
+      <ref name="LocalizedString"/>
+    </element>
+  </define>
+  <define name="forename">
+    <element name="forename">
+      <ref name="LocalizedString"/>
+    </element>
+  </define>
+  <define name="completeName">
+    <element name="completename">
+      <ref name="LocalizedString"/>
+    </element>
+  </define>
+  <define name="affiliation">
+    <element name="affiliation">
+      <optional>
+        <ref name="affiliationname"/>
+      </optional>
+      <zeroOrMore>
+        <ref name="affiliationdescription"/>
+      </zeroOrMore>
+      <ref name="organization"/>
+    </element>
+  </define>
+  <define name="affiliationname">
+    <element name="name">
+      <ref name="LocalizedString"/>
+    </element>
+  </define>
+  <define name="affiliationdescription">
+    <element name="description">
+      <ref name="FormattedString"/>
+    </element>
+  </define>
+  <define name="organization">
+    <element name="organization">
+      <ref name="orgname"/>
+      <optional>
+        <ref name="subdivision"/>
+      </optional>
+      <optional>
+        <ref name="abbreviation"/>
+      </optional>
+      <optional>
+        <ref name="uri"/>
+      </optional>
+      <zeroOrMore>
+        <ref name="org-identifier"/>
+      </zeroOrMore>
+      <zeroOrMore>
+        <ref name="contact"/>
+      </zeroOrMore>
+    </element>
+  </define>
+  <define name="orgname">
+    <element name="name">
+      <ref name="LocalizedString"/>
+    </element>
+  </define>
+  <define name="subdivision">
+    <element name="subdivision">
+      <ref name="LocalizedString"/>
+    </element>
+  </define>
+  <define name="abbreviation">
+    <element name="abbreviation">
+      <ref name="LocalizedString"/>
+    </element>
+  </define>
+  <define name="uri">
+    <element name="uri">
+      <optional>
+        <attribute name="type"/>
+      </optional>
+      <data type="anyURI"/>
+    </element>
+  </define>
+  <!-- TODO may change -->
+  <define name="contact">
+    <choice>
+      <ref name="address"/>
+      <ref name="phone"/>
+      <ref name="email"/>
+      <ref name="uri"/>
+    </choice>
+  </define>
+  <define name="phone">
+    <element name="phone">
+      <text/>
+    </element>
+  </define>
+  <define name="email">
+    <element name="email">
+      <text/>
+    </element>
+  </define>
+  <define name="address">
+    <element name="address">
+      <oneOrMore>
+        <!-- iso191606 TODO -->
+        <ref name="street"/>
+      </oneOrMore>
+      <ref name="city"/>
+      <optional>
+        <ref name="state"/>
+      </optional>
+      <ref name="country"/>
+      <optional>
+        <ref name="postcode"/>
+      </optional>
+    </element>
+  </define>
+  <define name="street">
+    <element name="street">
+      <text/>
+    </element>
+  </define>
+  <define name="city">
+    <element name="city">
+      <text/>
+    </element>
+  </define>
+  <define name="state">
+    <element name="state">
+      <text/>
+    </element>
+  </define>
+  <define name="country">
+    <element name="country">
+      <text/>
+    </element>
+  </define>
+  <define name="postcode">
+    <element name="postcode">
+      <text/>
+    </element>
+  </define>
+  <define name="person-identifier">
+    <element name="identifier">
+      <attribute name="type">
+        <choice>
+          <value>isni</value>
+          <value>uri</value>
+        </choice>
+      </attribute>
+      <text/>
+    </element>
+  </define>
+  <define name="org-identifier">
+    <element name="identifier">
+      <attribute name="type">
+        <choice>
+          <value>orcid</value>
+          <value>uri</value>
+        </choice>
+      </attribute>
+      <text/>
+    </element>
+  </define>
+  <define name="citation">
+    <element name="citation">
+      <ref name="CitationType"/>
+    </element>
+  </define>
+  <define name="CitationType">
+    <attribute name="bibitemid">
+      <data type="IDREF"/>
+    </attribute>
+    <zeroOrMore>
+      <ref name="locality"/>
+    </zeroOrMore>
+    <optional>
+      <ref name="date"/>
+    </optional>
+  </define>
+  <define name="date">
+    <element name="date">
+      <choice>
+        <data type="gYear"/>
+        <data type="date"/>
+      </choice>
+    </element>
+  </define>
+  <define name="locality">
+    <element name="locality">
+      <ref name="BibItemLocality"/>
+    </element>
+  </define>
+  <define name="BibItemLocality">
+    <attribute name="type">
+      <ref name="LocalityType"/>
+    </attribute>
+    <ref name="referenceFrom"/>
+    <optional>
+      <ref name="referenceTo"/>
+    </optional>
+  </define>
+  <define name="LocalityType">
+    <data type="string">
+      <param name="pattern">section|clause|part|paragraph|chapter|page|whole|table|annex|figure|note|list|example|volume|issue|locality:[a-zA-Z0-9_]+</param>
+    </data>
+  </define>
+  <define name="referenceFrom">
+    <element name="referenceFrom">
+      <text/>
+    </element>
+  </define>
+  <define name="referenceTo">
+    <element name="referenceTo">
+      <text/>
+    </element>
+  </define>
+  <!-- unlike UML, has id attribute; that results from including bibitem in a docmodel -->
+  <define name="bibitem">
+    <element name="bibitem">
+      <attribute name="id">
+        <data type="ID"/>
+      </attribute>
+      <ref name="BibliographicItem"/>
+    </element>
+  </define>
+  <define name="bibitem_no_id">
+    <element name="bibitem">
+      <ref name="BibliographicItem"/>
+    </element>
+  </define>
+  <define name="relaton_collection">
+    <element name="relaton-collection">
+      <optional>
+        <attribute name="type"/>
+      </optional>
+      <ref name="btitle"/>
+      <zeroOrMore>
+        <ref name="contributor"/>
+      </zeroOrMore>
+      <zeroOrMore>
+        <ref name="docrelation"/>
+      </zeroOrMore>
+    </element>
+  </define>
+  <define name="BibItemType" combine="choice">
+    <choice>
+      <value>article</value>
+      <value>book</value>
+      <value>booklet</value>
+      <value>conference</value>
+      <value>manual</value>
+      <value>proceedings</value>
+      <value>presentation</value>
+      <value>thesis</value>
+      <value>techreport</value>
+      <value>standard</value>
+      <value>unpublished</value>
+      <value>map</value>
+      <value>electronic resource</value>
+      <value>audiovisual</value>
+      <value>film</value>
+      <value>video</value>
+      <value>broadcast</value>
+      <value>graphic work</value>
+      <value>music</value>
+      <value>patent</value>
+      <value>inbook</value>
+      <value>incollection</value>
+      <value>inproceedings</value>
+    </choice>
+  </define>
+  <define name="BibliographicItem">
+    <optional>
+      <attribute name="type">
+        <ref name="BibItemType"/>
+      </attribute>
+    </optional>
+    <optional>
+      <ref name="fetched"/>
+    </optional>
+    <choice>
+      <oneOrMore>
+        <ref name="btitle"/>
+      </oneOrMore>
+      <ref name="formattedref"/>
+    </choice>
+    <zeroOrMore>
+      <ref name="bsource"/>
+    </zeroOrMore>
+    <zeroOrMore>
+      <ref name="docidentifier"/>
+    </zeroOrMore>
+    <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>
+    <optional>
+      <ref name="copyright"/>
+    </optional>
+    <zeroOrMore>
+      <ref name="docrelation"/>
+    </zeroOrMore>
+    <zeroOrMore>
+      <ref name="series"/>
+    </zeroOrMore>
+    <optional>
+      <ref name="medium"/>
+    </optional>
+    <zeroOrMore>
+      <ref name="bplace"/>
+    </zeroOrMore>
+    <zeroOrMore>
+      <ref name="extent"/>
+    </zeroOrMore>
+    <zeroOrMore>
+      <ref name="accesslocation"/>
+    </zeroOrMore>
+    <optional>
+      <ref name="bclassification"/>
+    </optional>
+    <optional>
+      <ref name="validity"/>
+    </optional>
+  </define>
+  <define name="btitle">
+    <element name="title">
+      <ref name="TypedTitleString"/>
+    </element>
+  </define>
+  <define name="bsource">
+    <element name="uri">
+      <ref name="TypedUri"/>
+    </element>
+  </define>
+  <define name="formattedref">
+    <element name="formattedref">
+      <ref name="FormattedString"/>
+    </element>
+  </define>
+  <define name="fetched">
+    <element name="fetched">
+      <choice>
+        <data type="dateTime"/>
+        <data type="date"/>
+      </choice>
+    </element>
+  </define>
+  <define name="validity">
+    <element name="validity">
+      <optional>
+        <ref name="validityBegins"/>
+      </optional>
+      <optional>
+        <ref name="validityEnds"/>
+      </optional>
+      <optional>
+        <ref name="validityRevision"/>
+      </optional>
+    </element>
+  </define>
+  <define name="validityBegins">
+    <element name="validityBegins">
+      <choice>
+        <data type="dateTime"/>
+        <data type="date"/>
+      </choice>
+    </element>
+  </define>
+  <define name="validityEnds">
+    <element name="validityEnds">
+      <choice>
+        <data type="dateTime"/>
+        <data type="date"/>
+      </choice>
+    </element>
+  </define>
+  <define name="validityRevision">
+    <element name="revision">
+      <choice>
+        <data type="dateTime"/>
+        <data type="date"/>
+      </choice>
+    </element>
+  </define>
+  <define name="TypedTitleString">
+    <optional>
+      <attribute name="type">
+        <ref name="TitleType"/>
+      </attribute>
+    </optional>
+    <ref name="FormattedString"/>
+  </define>
+  <define name="TitleType">
+    <choice>
+      <value>alternative</value>
+      <value>original</value>
+      <value>unofficial</value>
+      <value>subtitle</value>
+      <value>main</value>
+    </choice>
+  </define>
+  <define name="TypedUri">
+    <optional>
+      <attribute name="type"/>
+    </optional>
+    <data type="anyURI"/>
+  </define>
+  <define name="DateType">
+    <optional>
+      <attribute name="text"/>
+    </optional>
+    <optional>
+      <choice>
+        <data type="gYear"/>
+        <data type="date"/>
+      </choice>
+    </optional>
+  </define>
+  <define name="bdate">
+    <element name="date">
+      <attribute name="type">
+        <choice>
+          <value>published</value>
+          <value>accessed</value>
+          <value>created</value>
+          <value>implemented</value>
+          <value>obsoleted</value>
+          <value>confirmed</value>
+          <value>updated</value>
+          <value>issued</value>
+          <value>transmitted</value>
+          <value>copied</value>
+          <value>unchanged</value>
+        </choice>
+      </attribute>
+      <choice>
+        <group>
+          <element name="from">
+            <choice>
+              <data type="gYear"/>
+              <data type="date"/>
+            </choice>
+          </element>
+          <optional>
+            <element name="to">
+              <choice>
+                <data type="gYear"/>
+                <data type="date"/>
+              </choice>
+            </element>
+          </optional>
+        </group>
+        <element name="on">
+          <choice>
+            <data type="gYear"/>
+            <data type="date"/>
+          </choice>
+        </element>
+      </choice>
+    </element>
+  </define>
+  <define name="docidentifier">
+    <element name="docidentifier">
+      <optional>
+        <attribute name="type"/>
+      </optional>
+      <text/>
+    </element>
+  </define>
+  <define name="bclassification">
+    <element name="classification">
+      <optional>
+        <attribute name="type"/>
+      </optional>
+      <text/>
+    </element>
+  </define>
+  <define name="bplace">
+    <element name="place">
+      <text/>
+    </element>
+  </define>
+  <define name="medium">
+    <element name="medium">
+      <optional>
+        <ref name="form"/>
+      </optional>
+      <optional>
+        <ref name="size"/>
+      </optional>
+      <optional>
+        <ref name="scale"/>
+      </optional>
+    </element>
+  </define>
+  <define name="form">
+    <element name="form">
+      <text/>
+    </element>
+  </define>
+  <define name="size">
+    <element name="size">
+      <text/>
+    </element>
+  </define>
+  <define name="scale">
+    <element name="scale">
+      <text/>
+    </element>
+  </define>
+  <define name="accesslocation">
+    <element name="accesslocation">
+      <text/>
+    </element>
+  </define>
+  <define name="extent">
+    <element name="extent">
+      <ref name="BibItemLocality"/>
+    </element>
+  </define>
+  <define name="series">
+    <element name="series">
+      <optional>
+        <attribute name="type">
+          <choice>
+            <value>main</value>
+            <value>alt</value>
+          </choice>
+        </attribute>
+      </optional>
+      <choice>
+        <ref name="btitle"/>
+        <ref name="formattedref"/>
+      </choice>
+      <optional>
+        <ref name="bplace"/>
+      </optional>
+      <optional>
+        <ref name="seriesorganization"/>
+      </optional>
+      <optional>
+        <ref name="abbreviation"/>
+      </optional>
+      <optional>
+        <ref name="seriesfrom"/>
+      </optional>
+      <optional>
+        <ref name="seriesto"/>
+      </optional>
+      <optional>
+        <ref name="seriesnumber"/>
+      </optional>
+      <optional>
+        <ref name="seriespartnumber"/>
+      </optional>
+    </element>
+  </define>
+  <define name="seriesorganization">
+    <element name="organization">
+      <text/>
+    </element>
+  </define>
+  <define name="seriesfrom">
+    <element name="from">
+      <choice>
+        <data type="dateTime"/>
+        <data type="date"/>
+        <data type="gYear"/>
+      </choice>
+    </element>
+  </define>
+  <define name="seriesto">
+    <element name="to">
+      <choice>
+        <data type="dateTime"/>
+        <data type="date"/>
+        <data type="gYear"/>
+      </choice>
+    </element>
+  </define>
+  <define name="seriesnumber">
+    <element name="number">
+      <text/>
+    </element>
+  </define>
+  <define name="seriespartnumber">
+    <element name="partnumber">
+      <text/>
+    </element>
+  </define>
+  <define name="biblionote">
+    <element name="note">
+      <ref name="FormattedString"/>
+    </element>
+  </define>
+  <define name="abstract">
+    <element name="abstract">
+      <ref name="FormattedString"/>
+    </element>
+  </define>
+  <define name="copyright">
+    <element name="copyright">
+      <ref name="from"/>
+      <optional>
+        <ref name="to"/>
+      </optional>
+      <ref name="owner"/>
+    </element>
+  </define>
+  <define name="from">
+    <element name="from">
+      <data type="gYear"/>
+    </element>
+  </define>
+  <define name="to">
+    <element name="to">
+      <data type="gYear"/>
+    </element>
+  </define>
+  <define name="owner">
+    <element name="owner">
+      <ref name="ContributorInfo"/>
+    </element>
+  </define>
+  <define name="docrelation">
+    <element name="relation">
+      <attribute name="type">
+        <choice>
+          <value>obsoletes</value>
+          <value>updates</value>
+          <value>updatedBy</value>
+          <value>complements</value>
+          <value>derivedFrom</value>
+          <value>translatedFrom</value>
+          <value>adoptedFrom</value>
+          <value>equivalent</value>
+          <value>identical</value>
+          <value>nonequivalent</value>
+          <value>includedIn</value>
+          <value>includes</value>
+          <value>instance</value>
+          <value>partOf</value>
+        </choice>
+      </attribute>
+      <element name="bibitem">
+        <ref name="BibliographicItem"/>
+      </element>
+      <zeroOrMore>
+        <ref name="locality"/>
+      </zeroOrMore>
+    </element>
+  </define>
+  <!--
+    Anycontents = mixed {
+    https://github.com/relaxng/jing-trang/issues/211
+    https://lists.oasis-open.org/archives/office/200808/msg00024.html
+    https://lists.oasis-open.org/archives/office/200808/msg00099.html
+    For this to work, we will actually strip any attributes in the Anycontents before
+    passing it for validation. Horrible I know, but there are no good alternatives
+    that also allow us to do grammar inheritance
+    (attribute * { text } | Any)*
+           Any*
+    }
+  -->
+  <define name="AnyElement">
+    <element>
+      <anyName/>
+      <choice>
+        <text/>
+        <ref name="AnyElement"/>
+      </choice>
+    </element>
+  </define>
+</grammar>