metanorma-iso 1.0.0

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,46 @@
+# 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. The project team will review and investigate all complaints, and will respond in a way that it deems 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/Makefile

@@ -0,0 +1,39 @@
+SRC  := $(wildcard draft-*.adoc)
+TXT  := $(patsubst %.adoc,%.txt,$(SRC))
+XML  := $(patsubst %.adoc,%.xml,$(SRC))
+HTML := $(patsubst %.adoc,%.html,$(SRC))
+NITS := $(patsubst %.adoc,%.nits,$(SRC))
+
+SHELL := /bin/bash
+# Ensure the xml2rfc cache directory exists locally
+IGNORE := $(shell mkdir -p $(HOME)/.cache/xml2rfc)
+
+all: $(TXT) $(HTML) $(XML) $(NITS)
+
+clean:
+	rm -f $(TXT) $(HTML) $(XML)
+
+%.xml: %.adoc
+	#bundle exec asciidoctor -r ./lib/glob-include-processor.rb -r asciidoctor-rfc -b rfc2 $^ --trace > $@
+	bundle exec asciidoctor -r ./lib/glob-include-processor.rb -r asciidoctor-rfc -b rfc2 -a flush-biblio=true $^ --trace > $@
+
+%.xml3: %.adoc
+	#bundle exec asciidoctor -r ./lib/glob-include-processor.rb -r asciidoctor-rfc -b rfc2 $^ --trace > $@
+	bundle exec asciidoctor -r ./lib/glob-include-processor.rb -r asciidoctor-rfc -b rfc3 -a flush-biblio=true $^ --trace > $@
+
+%.txt: %.xml
+	xml2rfc --text $^ $@
+
+%.html: %.xml
+	xml2rfc --html $^ $@
+
+%.nits: %.txt
+	VERSIONED_NAME=`grep :name: $*.adoc | cut -f 2 -d ' '`; \
+	cp $^ $${VERSIONED_NAME}.txt && \
+	idnits --verbose $${VERSIONED_NAME}.txt > $@ && \
+	cp $@ $${VERSIONED_NAME}.nits && \
+	cat $${VERSIONED_NAME}.nits
+
+open:
+	open *.txt
+

data/README.adoc

@@ -0,0 +1,882 @@
+= AsciiISO: Asciidoctor processor for ISO standards
+
+image:https://img.shields.io/gem/v/metanorma-iso.svg["Gem Version", link="https://rubygems.org/gems/metanorma-iso"]
+image:https://img.shields.io/travis/riboseinc/metanorma-iso/master.svg["Build Status", link="https://travis-ci.org/riboseinc/metanorma-iso"]
+image:https://codeclimate.com/github/riboseinc/metanorma-iso/badges/gpa.svg["Code Climate", link="https://codeclimate.com/github/riboseinc/metanorma-iso"]
+
+WARNING: This gem is still under development.
+
+== Functionality
+
+This gem processes http://asciidoctor.org/[Asciidoctor] documents following
+a template for generating ISO International Standards. The following
+outputs are generated.
+
+* (Optional) An HTML preview generated directly from the Asciidoctor document,
+using native Asciidocot 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 bracketting terms your in AsciiMathML
+expressions.
+* an XML representation of the document, intended as a document model for ISO
+International Standards. 
+* The XML representation is processed in turn to generate the following outputs
+as end deliverable ISO standard drafts.
+** Microsoft Word output (`.doc`), following the style conventions of the 
+https://www.iso.org/iso-templates.html[ISO Standard Microsoft Word template]. 
+** HTML. For ISO, two HTML files are generated: the `.html` file follows ISO
+conventions in rendering, which looks very similar to the Word output, while
+the `-alt.html` file has richer styling.
+** PDF. Not supported for the ISO gem, but available for other other specification,
+generated from the HTML file.
+
+This AsciiDoc syntax for writing ISO standards is hereby named "AsciiISO".
+
+This README provides an overview of the functionality of the gem; see also
+https://github.com/riboseinc/metanorma-iso/wiki/Guidance-for-authoring[Guidance for authoring]
+ISO standards using the gem. The 
+https://github.com/riboseinc/metanorma-iso/wiki/Quickstart-Guide[Quickstart guide]
+gives a summary overview.
+
+== Usage
+
+The preferred way to invoke this gem is via the `metanorma` script:
+
+[source,console]
+----
+$ metanorma --type iso a.adoc                   # output HTML and DOC
+$ metanorma --type csd --extensions html a.adoc # output just HTML
+$ metanorma --type csd --extensions doc a.adoc  # output just DOC
+$ metanorma --type csd --extensions xml a.adoc  # output CSD XML
+----
+
+The gem translates the document into ISO XML format, and then
+validates its output against the ISO 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 DOC.
+
+The gem can also be invoked directly within asciidoctor, though this is deprecated:
+
+[source,console]
+----
+$ asciidoctor -b iso -r 'metanorma-iso' a.adoc  
+----
+
+If you do not invoke the `iso` backend explicitly, the AsciiISO source will be
+treated as generic Asciidoc markup, and will output an HTML preview that 
+ignores the ISO-specific modifications to the markup:
+
+[source,console]
+----
+$ asciidoctor a.adoc  
+----
+
+=== Installation
+
+If you are using a Mac, 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-iso
+----
+
+
+=== Content Warnings
+
+The gem also realises several format
+checks as prescribed in ISO/IEC DIR 2: 2018, and warns the user about them in the
+console:
+
+* Numbers with what looks like dots instead of commas for decimal points.
+
+* Groups of numbers without spacing for every three digits. (The gem attempts
+to ignore ISO references.)
+
+* No space before percent sign.
+
+* No bracketing of tolerance in percentage (e.g. `15 ± 7 % .`)
+
+* No recommendations, permissions or requirements (detected by keyword) in:
+foreword, scope, introduction, term examples and examples, notes, footnotes.
+
+* No subclauses that are the only child of a clause. (In clauses, annexes, or
+scopes.)
+
+* 5 levels of subclause nesting. (Never actuated, AsciiDoc only permits 4
+levels of subsections.)
+
+* Non-ISO/IEC reference turning up as normative.
+
+* Term definition starts with an article, or ends with a period.
+
+* Title intro or title part appears in only one of French or English.
+
+In addition, the gem checks all terms cited from the IEV Electropedia against
+the online IEV Electropedia entry, and issues a warning if the term is different.
+
+== Approach
+=== Document model
+
+The document model ("IsoDoc") used in document generation
+intends to introduce rigour into the ISO
+standards authoring process; the existing 
+https://www.iso.org/iso-templates.html[Microsoft Word template from ISO]
+do not support such rigour down to the element level. It also introduces
+flexibility by decoupling the document structure from its presentation.
+
+The ISO International Standard format is prescribed in
+http://www.iec.ch/members_experts/refdocs/iec/isoiecdir-2%7Bed7.0%7Den.pdf[ISO/IEC DIR 2 "Principles and rules for the structure and drafting of ISO and IEC documents"],
+to a level amenable to an explicit document model. A formal document
+model would allow checking for consistency in format and content, and expedite
+authoring and quality control of ISO standards. Authoring standards through a 
+more abstract formal model also permit enhanced functionality such as 
+cross-reference link checking and auto-numbering of sections, figures, tables and formulas.
+Outputting a document in different languages also becomes straightforward.
+
+The document model for ISO Standards specifically is derived from a more general
+https://github.com/riboseinc/isodoc-models[StandardDocument model]. Other
+ISO-like standards can also be derived from this more general model;
+CSD (https://github.com/riboseinc/csd, https://github.com/riboseinc/metanorma-csd)
+is one such instance.
+
+The document model for ISO Standards contains all the structures described
+in ISO/IEC DIR 2. It is expressed as a
+link:lib/metanorma/iso/isostandard.rnc[Relax NG Compact schema]; actual
+validation occurs against its link:lib/metanorma/iso/isostandard.rng[full Relax
+NG counterpart]. 
+
+=== Asciidoctor
+
+Asciidoctor has been selected as the authoring tool to generate the document
+model representation of ISO 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 rigour 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 and HTML; so it can be used to preview the file as it is being
+authored. However the gem natively outputs HTML and Word output, so there should
+not be much need for this.
+
+In order to generate HTML preview output close to what is intended
+in the ISO standard, the Asciidoc
+document includes a fair amount of formatting instructions (e.g. disabling
+section numbering where appropriate, the titling of Appendixes as Annexes), as
+well as ISO boilerplate text, and predefined section headers (sections are
+recognised by fixed titles such as `Normative References`). Authoring ISO
+standards in this fashion assumes that users will be populating an Asciidoc
+template, and not removing needed formatting instructions.
+
+Asciidoctor has some formatting constraints because of its own document model,
+that users need to be aware. For example, Asciidoc has a strict division between
+inline and block elements, which disallows certain kinds of nesting; so a list
+cannot be embedded within a paragraph, it can only constitute its own paragraph
+(though lists themselves can be nested within each other). Asciidoctor also disallows
+multiple paragraphs in footnotes, 
+http://discuss.asciidoctor.org/footnotes-with-paragraph-breaks-td4130.html[by design].
+(The document model does not impose this constraint, so you could edit the generated
+XML to break up paragraphs within a footnote.)
+
+[[model_additions]]
+== Asciidoctor model additions
+
+=== Section titles
+ISO has special section types: "Scope", "Normative References", "Terms and Definitions", "Symbols and Abbreviated Terms", "Bibliography". By default, these are identified in Asciidoc by using those titles. The gem allows you to override the title by using a `heading` attribute on the node, so that the actual title in your Asciidoc can be something different; that is useful, for example, if you are translating the document into different languages. So:
+
+[source,asciidoctor]
+--
+[heading=scope]
+== 范围
+--
+
+Note that both the XML population, and the isodoc gem will overwrite any supplied title. If you are translating ISO documents into other languages, you will still need access to versions of the metanorma-iso and isodoc gems in those languages.
+
+=== Obligation
+The obligation of sections (whether they are normative or informative) is indicated
+with the attribute "obligation". For most sections, this is fixed; for annexes and clauses, the
+default value of the obligation is "normative", and users need to set the obligation
+to "informative" as a section attribute.
+
+[source,asciidoctor]
+--
+[[AnnexA]]
+[appendix,obligation=informative]
+== Determination of defects
+--
+
+=== Term markup
+
+To ensure the structure of Terms and Definitions is captured accurately, the following
+macros are defined, and must be used to mark up their respective content:
+
+`alt:[TERM]`:: for alternative terms
+`deprecated:[TERM]`:: for deprecated terms
+`domain:[TERM]`:: for term domains
+
+The macro contents can contain their own markup.
+
+[source,asciidoctor]
+--
+=== paddy 
+alt:[_paddy_ rice]
+deprecated:[#[smallcap]#cargo# rice]
+domain:[rice]
+
+_paddy_ (<<paddy>>) from which the husk only has been removed
+--
+
+=== Terms and Definitions markup
+
+If the Terms and Definitions of a standard are partly or fully sourced from
+another standard, that standard is cited in a `source` attribute to the section,
+which is set to the reference anchor of the standard (given under the Normative
+Referencecs)..
+The boilerplate of the Terms and Definitions section is adjusted accordingly.
+
+[source,asciidoctor]
+--
+[source=ISO712]
+== Terms and Definitions
+--
+
+Multiple sources are allowed, and need to be quoted and comma-delimited:
+
+[source,asciidoctor]
+--
+[source="ISO712,ISO24333"]
+== Terms and Definitions
+--
+
+
+=== Paragraph alignment
+
+Alignment is defined as an attribute for paragraphs:
+
+[source,asciidoctor]
+--
+[align=left]
+This paragraph is aligned left
+
+[align=right]
+This paragraph is aligned right
+
+[align=center]
+This paragraph is aligned center
+
+[align=justified]
+This paragraph is justified, which is the default
+--
+
+=== Reviewer notes
+
+Reviewer notes are encoded as sidebars, and can be separated at a distance from the
+text they are annotating; the text they are annotating is indicated through anchors. 
+Reviewer notes are only rendered if the document has a `:draft:` attribute.
+
+The following attributes on reviewer notes are mandatory:
+
+* `reviewer` attribute (naming the reviewer) 
+* the starting target anchor of the note (`from` attribute)
+
+The following attributes are optional:
+
+* `date` attribute, optionally including the time (as xs:date or xs:datetime)
+* the ending target anchor of the note (`to` attribute)
+
+The span of text covered by the reviewer note is from the start of the
+text encompassed by the `from` element, to the end of the text encompassed
+by the `to` element. If only the `from` element supplied, the reviewer note
+covers the `from` element. The `from` and `to` elements can be bookmarks,
+which cover no space.
+
+[source,asciidoctor]
+--
+[[clause_address_profile_definition]]
+=== Address Profile Definition (AddressProfileDescription)
+
+[[para1]]
+This is a clause address [[A]]profile[[B]] definition
+
+[reviewer="Nick Nicholas",date=20180125T0121,from=clause_address_profile_definition,to=para1]
+****
+I do not agree with this statement.
+****
+
+[reviewer="Nick Nicholas",date=20180125T0121,from=A,to=B]
+****
+Profile?!
+****
+--
+
+=== Strikethrough and Small Caps
+
+The following formatting macros are used for strikethrough and small caps text:
+
+[source,asciidoctor]
+--
+[strike]#strike through text#
+[smallcap]#small caps text#
+--
+
+=== Count of table header and footer rows
+
+In Asciidoc, a table can have at most one header row or footer row. In ISO,
+a nominal single header row is routinely broken up into multiple rows in order
+to accommodate units or symbols, that line up against each other, though
+they are displayed as merged cells with no grid between them. To address this,
+tables can be marked up with an optional `headerrows` attribute:
+
+[source,asciidoctor]
+--
+[headerrows=2]
+|===
+.2+|Defect 4+^| Maximum permissible mass fraction of defects in husked rice +
+stem:[w_max]
+| in husked rice | in milled rice (non-glutinous) | in husked parboiled rice | in milled parboiled rice
+
+| Extraneous matter: organic footnote:[Organic extraneous matter includes foreign seeds, husks, bran, parts of straw, etc.] | 1,0 | 0,5 | 1,0 | 0,5
+|===
+--
+
+=== Inline clause numbers
+
+For some clauses (notably test methods), the clause heading appears inline with the clause, instead of being separated on a different line. This is indicated in Asciidoc by the option
+attribute `inline-header`:
+
+[source,asciidoctor]
+--
+[%inline-header]
+[[AnnexA-2-1]]
+==== Sample divider, 
+
+consisting of a conical sample divider
+--
+
+=== Bibliographic details
+
+Citations can include details of where in the document the citation is located; these
+are entered by suffixing the type of locality, then an equals sign, then the reference. 
+The word "whole" on its own is also treated as a locality. Multiple
+instances of locality and reference can be provided, delimited by comma or colon. Any trailing
+text after the sequence of locality=reference (or locality, space, reference) are treated
+as substitute text, as would occur normally in an Asciidoctor crossreference. For
+example:
+
+[source,asciidoctor]
+--
+<<ISO712,the foregoing reference>>     # renders as: the foregoing reference
+<<ISO712,section=5, page 8-10>>         # renders as: ISO 712, Section 5, Page 8-10
+<<ISO712,section=5, page=8-10: 5:8-10>> # renders as ISO 712, 5:8-10 ("5:8-10" treated as replacement text for all the foregoing)
+<<ISO712,whole>>                        # renders as: ISO 712, Whole of text
+--
+
+The references cannot contain spaces. Any text following the sequence of localities
+will be displayed instead of the localities.
+
+A custom locality can be entered by prefixing it with `locality:`:
+
+[source,asciidoctor]
+--
+<<ISO712,locality:frontispiece=5, page=8-10>>         # renders as: ISO 712, Frontispiece 5, Page 8-10
+--
+
+Custom localities may not contain commas, colons, or space. Localities with the `locality:`
+prefix are recognised in internationalisation configuration files.
+
+=== Additional warning types
+
+Asciidoctor natively supports the ISO admonitions "Caution", "Warning", and "Important"
+through its admonition syntax:
+
+[source,asciidoctor]
+--
+CAUTION: This is a single-block caution
+
+[WARNING]
+====
+This is a
+
+multiple-block warning
+====
+--
+
+If the admonitions "Danger" and "Safety Precaution" are needed, they should be indicated
+through a `type` attribute, which will override the admonition type appearing in the Asciidoc:
+
+[source,asciidoctor]
+--
+[type=Danger]
+CAUTION: This is a single-block caution
+
+[WARNING,type=Safety Precaution]
+====
+This is a
+
+multiple-block warning
+====
+--
+
+=== Block Quotes
+
+As in normal Asciidoctor, block quotes are preceded with an author and a citation;
+but the citation is expected to be in the same format as all other citations, 
+a cross-reference optionally followed by text, which may include the bibliographic
+sections referenced:
+
+[source,asciidoctor]
+--
+[quote, ISO, "ISO7301,section 1"]
+_____
+This International Standard gives the minimum specifications for rice (_Oryza sativa_ L.) 
+which is subject to international trade. It is applicable to the following types: husked rice 
+and milled rice, parboiled or not, intended for direct human consumption. It is neither 
+applicable to other products derived from rice, nor to waxy rice (glutinous rice).
+_____
+--
+
+=== Image size
+
+The value `auto` is accepted for image width and height attributes. It is only passed on
+to HTML output; if the output is to Word, both the width and height attributes are stripped
+from the image.
+
+[source,asciidoctor]
+--
+[height=90,width=auto]
+image::logo.jpg
+--
+
+=== Sections embedded more than 5 levels
+
+Asciidoctor permits only 5 levels of section embedding (not counting the document title).
+Standards do contain more levels of embedding; ISO/IEC DIR 2 only considers it a problem
+if there are more than 7 levels of embedding. To realise higher levels of embedding,
+prefix a 5-level section title with the attribute `level=`:
+
+[source,asciidoctor]
+--
+====== Clause 5
+
+[level=6]
+===== Clause 6
+
+[level=7]
+====== Clause 7A
+
+[level=7]
+====== Clause 7B
+
+[level=6]
+====== Clause 6B
+
+====== Clause 5B
+--
+
+This generates the following ISO XML:
+
+[source,xml]
+--
+<clause id="_" inline-header="false" obligation="normative">
+	<title>
+		Clause 5 
+	</title>
+	<clause id="_" inline-header="false" obligation="normative">
+		<title>
+			Clause 6 
+		</title>
+		<clause id="_" inline-header="false" obligation="normative">
+			<title>
+				Clause 7A 
+			</title>
+		</clause>
+		<clause id="_" inline-header="false" obligation="normative">
+			<title>
+				Clause 7B 
+			</title>
+		</clause>
+	</clause>
+	<clause id="_" inline-header="false" obligation="normative">
+		<title>
+			Clause 6B 
+		</title>
+	</clause>
+</clause>
+<clause id="_" inline-header="false" obligation="normative">
+	<title>
+		Clause 5B 
+	</title>
+</clause>
+--
+
+=== PlantUML
+
+The http://plantuml.com[PlantUML] diagramming tool is integrated with Asciidoctor
+in this gem, as a literal block with the style attribute `plantuml`:
+
+[source,asciidoctor]
+--
+[plantuml]
+....
+@startuml
+Alice -> Bob: Authentication Request
+Bob --> Alice: Authentication Response
+
+Alice -> Bob: Another authentication Request
+Alice <-- Bob: another authentication Response
+@enduml
+....
+--
+
+The integration runs PlantUML for each such block, generating a PNG image.
+The images are stored in the `plantuml` directory, and linked into the output
+document in place of the PlantUML.
+
+PlantUML needs to be installed by users separately, and accesssible from the
+command line:
+
+* `brew install plantuml` on MacOS.
+* For Linux, link the PlantUML jar file into a command line executable; see
+`.travis.yml` for an example.
+
+If PlantUML is not installed locally, the source PlantUML is incorporated into
+the output document as sourcecode. 
+
+=== Features not visible in HTML preview
+
+The gem uses built-in Asciidoc formatting as much as possible, so that users
+can retain the ability to preview documents; for _Terms and Definitions_
+clauses, which have a good deal of explicit structure, macros have been
+introduced for semantic markup (admitted terms, deprecated terms, etc). 
+
+The default HTML output of an Asciidoc-formatted ISO document is quite close to the
+intended final output, with the following exceptions, and with the additional
+exceptions listed <<model_additions,above>> as markup introduced for ISO markup. 
+Note that the final
+outputs of the conversion (Microsoft Word, PDF, HTML) do not have these exceptions,
+and comply with the ISO Standard specifications.
+
+* _Terms and Definitions_: each term is marked up as an unnumbered subclause,
+the semantic markup of alternate and other terms is not rendered visually.
+
+* _Formulas_: Asciidoctor has no provision for the automated numbering of
+isolated block formulas ("stem"), and does not display the number assigned a
+block formula in its default HTML processor—although it does provide automated
+numbering of examples. Formula numbering is provided in the final outputs
+of the conversion.
+
+* _Missing elements_: The document model does not yet include Asciidoc elements
+that do not appear to be relevant to ISO Standards; these will be ignored in
+generating ISO XML. Those elements include:
+** sidebars (`aside`) (as distinct from warnings),
+** ASCII art/preformatted text (`literal`) (as distinct from sourcecode listings),
+** page breaks (`thematic break`).
+
+* _Markup_: Some connecting text which is used to convey markup structure is
+left out: in particular, `DEPRECATED` and `SOURCE` (replaced by formatting
+macros).
+
+* _Tables_: Table footnotes are treated like all other footnotes: they are
+rendered at the bottom of the document, rather than the bottom of the table,
+and they are not numbered separately.
+
+* _Cross-references_: Footnoted cross-references are indicated with the reference
+text `fn` in isolation, or `fn:` as a prefix to the reference text. The default
+HTML processor leaves these as is: if no reference text is given, only `fn`
+will be displayed (though it will still hyperlink to the right reference).
+
+* _References_: The convention for references is that ISO documents are cited
+without brackets by ISO number, and optionally year, whether they are normative
+or in the bibliography (e.g. `ISO 20483:2013`); while all other references are
+cited by bracketed number in the bibliography (e.g. `[1]`). The default HTML
+processor treats all references the same, and will bracket them (e.g. `[ISO
+20483:2013]`). For the same reason, ISO references listed in the bibliography
+will be listed under an ISO reference, rather than a bracketed number.
+
+* _References_: References are rendered cited throughout, since they are
+automated. For that reason, if reference is to be made to both an undated and a
+dated version of an ISO reference, these need to be explicitly listed as
+separate references. (This is not done in the Rice model document, which lists
+ISO 6646, but under _Terms and Definitions_ cites the dated ISO 6646:2011.
+
+* _References_: ISO references that are undated but published have their date
+indicated under the ISO standards format in an explanatory footnote. Because of
+constraints introduced by Asciidoctor, that explanation is instead given in
+square brackets in Asciidoc format.
+
+* _Annexes_: Subheadings cannot preserve subsection numbering, while also
+appearing inline with their text (e.g. Rice document, Annex B.2): they appear
+as headings in separate lines.
+
+* _Annexes_: Cross-references to Annex subclauses are automatically prefixed
+with `Clause` rather than `Annex` or nothing.
+
+* _Metadata_: Document metadata such as document numbers, technical committees
+and title wording are not rendered in the default HTML output.
+
+* _Patent Notice_: Patent notices are treated and rendered as a subsection of
+the introduction, with an explicit subheading.
+
+* _Numbering_: The numbering of figures and tables is sequential in the default
+HTML processor: it does not include the Clause or Annex number. This,
+_Figure 1_, not _Figure A.1_.
+
+* _Notes_: There is no automatic note numbering by the default HTML processor.
+
+* _Review Notes_: The reviewer on the review note is not displayed.
+
+* _Keys_: Keys to formulas and figures are expected to be marked up as
+definition lists consistently, rather than as inline prose.
+
+* _Figures_: Simple figures are marked up as images, figures containing
+subfigures as examples. Numbering by the default HTML processor may be
+inconsistent. Subfigures are automatically numbered as independent figures.
+
+* _Markup_: The default HTML processor does not support CSS extensions such as
+small caps or strike through, though these can be marked up as CSS classes
+through custom macros in Asciidoctor: a custom CSS stylesheet will be needed to
+render them.
+
+== Bibliography integration
+
+Bibliographic entries for ISO standards are expected to use the standard document
+identifier as the item label; e.g.
+
+[source,asciidoctor]
+--
+* [[[ref1,ISO 712]]], _Cereals and cereal products -- Determination of moisture content -- Reference method_
+--
+
+By default, the `isobib` gem is used to look up the reference details for 
+any item label prefixed with `ISO` on the ISO web site. The full bibliographic details 
+of the item are screenscraped from the ISO site and inserted into the XML file 
+(although only the title of the reference is used in rendering). The
+http://www.electropedia.org[Electropedia] termbank is queried in validation, to confirm
+that the cited entries in Terms and Definitions are the same as what is cited online;
+those queries are routed through the `iev` gem
+
+[[cache]]
+The results of all `isobib` searches done to date, across all documents,
+are cached in the global cache file `~/.relaton-bib.pstore`, 
+so they do not need to be re-fetched each time a document is processed. 
+(The web query takes a few seconds per reference.)
+
+The results of all `isobib` searches done to date for the current document
+(`filename.adoc`) are stored in the same directory as the current document,
+in the file `{filename}.relaton.pstore`. The local cache overrides entries in
+the global cache, and can be manually edited. The local cache is only used
+if the `:local-cache:` document attribute is set.
+
+If the document attribute `:no-isobib:` is set, the reference details for
+items are not looked up via `isobib`, and the `isobib` caches are not used.
+If the document attribute `:no-isobib-cache:` is set, the reference details for
+items are still looked up via `isobib`, but the `isobib` caches are not used.
+
+Any entry in the cache that corresponds to an undated ISO reference fetches its details
+from the latest available entry on the ISO web site. If the entry is more than 60
+days old, it is refetched.
+
+The results of all `iev` searches done to date across all documents are cached
+in the global cache fule `~/iev.pstore`, and the results of all `iev` searches 
+done to date for the current document are stored in the same directory as the
+current document, in the file `(filename).iev.pstore`.
+
+== Document Attributes
+
+The gem relies on Asciidoctor document attributes to provide necessary
+metadata about the document. These include:
+
+`:nodoc:`:: Do not generate Word and HTML output, only generate XML output.
+Can be used as a command-line option (like all other document attributes):
+`asciidoctor -a nodoc -b iso -r "metanorma-iso" a.adoc`
+
+`:novalid:`:: Suppress validation.
+
+`:flush-caches:`:: If set, delete and reinitialise the <<cache,cache>> of `isobib` searches
+for ISO references from the ISO web site.
+
+`:no-isobib:`:: If set, do not use the `isobib` or `iev` gem functionality to look up
+ISO and IEV references online, nor the <<cache,cache>> of `isobib` and `iev` searches.
+
+`:no-isobib-cache:`:: If set, use the `isobib` and `iev` gem functionality to look up
+ISO and IEV references online, but do not use the <<cache,cache>> of `isobib` and `iev` searches.
+
+`:local-cache:`:: Use the local isobib and iev search caches to override the global isobib and iev search
+caches.
+
+`:i18nyaml:`:: Name of YAML file of internationalisation text, to use instead
+of the built-in English, French or Chinese text used to label parts of the document
+(e.g. "Table", "Foreword", boilerplate text for Normative References, etc.)
+Use if you wish to output an ISO standard in a language other than those three.
+A sample YAML file for English, with "Foreword" replaced with "Frontispiece",
+is available at link:spec/examples/english.yaml[].
+
+`:docnumber:`:: The ISO document number (mandatory)
+
+`:tc-docnumber:`:: The document number assigned by the Technical committee
+
+`:partnumber:`:: The ISO document part number. (This can be "part-subpart" if this is an IEC document.)
+
+`:edition:`:: The document edition
+
+`:revdate:`:: The date the document was last updated
+
+`:draft:`:: The document draft (used in addition to document stage, for multiple iterations: expected format _X.Y_)
+
+`:copyright-year:`:: The year which will be claimed as when the copyright for
+the document was issued
+
+`:library-ics:` :: The ICS (International Categorization for Standards) number for the standard. There may be more than one ICS for a document; if so, they should be comma-delimited. (The ics identifier is added to the document metadata, but is not output to the current document templates.)
+
+`:title-intro-en:`:: The introductory component of the English title of the
+document
+
+`:title-main-en:`:: 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)
+
+`:title-part-en:`:: The English title of the document part
+
+`:title-intro-fr:`:: The introductory component of the French title of the
+document. (This document template presupposes authoring in English; a different
+template will be needed for French, including French titles of document
+components such as annexes.)
+
+`:title-main-fr:`:: The main component of the French title of the document
+(mandatory). 
+
+`:title-part-fr:`:: The French title of the document part
+
+`:doctype:`:: The document type (see
+https://www.iso.org/deliverables-all.html[ISO deliverables: The different types of ISO publications]
+) (mandatory). The permitted types are:
+`international-standard, technical-specification, technical-report,
+publicly-available-specification, international-workshop-agreement, guide`.
+
+`:docstage:`:: The stage code for the document status (see
+https://www.iso.org/stage-codes.html[International harmonized stage codes])
+
+`:docsubstage:`:: The substage code for the document status (see
+https://www.iso.org/stage-codes.html[International harmonized stage codes])
+
+`:iteration:`:: The iteration of a stage, in case there have been multiple drafts
+(e.g. `2` on a `CD`: this is the second iteration through the `CD` stage).
+
+`:secretariat:`:: The national body acting as the secretariat for the document
+in the deafting stage
+
+`:technical-committee-number:`:: The number of the relevant ISO technical
+committee
+
+`:technical-committee-type:``:: The type of the relevant technical committee. Defaults
+to `TC` if not supplied. Values: `TC1, `PC`, `JTC`, `JPC`.
+
+`:technical-committee:`:: The name of the relevant ISO technical committee
+(mandatory)
+
+`:subcommittee-number:`:: The number of the relevant ISO subcommittee
+
+`:subcommittee-type:`:: The type of the relevant ISO subcommittee. Defaults to
+`SC` if not supplied. Values: `SC`, `JSC`.
+
+`:subcommittee:`:: The name of the relevant ISO subcommittee
+
+`:workgroup-number:`:: The number of the relevant ISO workgroup
+
+`:workgroup-type:`:: The type of the relevant ISO workgroup. Defaults to `WG` if
+not supplied. Example values: `JWG`, `JAG`, `AG` (advisory group), `AHG`, `SWG`, 
+`SG`, `MA` (maintenance agency), `CORG`, `JCG`, `CAG`
+
+`:workgroup:`:: The name of the relevant ISO workgroup
+
+`:language:` :: The language of the document (`en` or `fr`). Defaults to `en`.
+
+`:script:` :: The script of the document (defaults to `Latn`). Must be supplied as
+`Hans` for Simplified Chinese.
+
+`:publisher:`:: The standards agency publishing the standard; can be multiple
+(comma-delimited). Defaults to `ISO`.
+
+`:body-font:`:: Font for body text; will be inserted into CSS. Defaults to
+Cambria for Latin script, SimSun for Simplified Chinese.
+
+`:header-font:`:: Font for headers; will be inserted into CSS. Defaults to
+Cambria for Latin script, SimHei for Simplified Chinese.
+
+`:monospace-font`:: Font for monospace; will be inserted into CSS. Defaults to
+Courier New.
+
+`:htmlstylesheet`:: SCSS stylesheet to use for HTML output. Defaults to built in stylesheet,
+which adheres with ISO formatting requirements. Recommend against overriding this.
+
+`:htmlcoverpage`:: HTML template for cover page. Defaults to built in template. Recommend against overriding this.
+
+`:htmlintropage`:: HTML template for introductory section. Defaults to built in template. Recommend against overriding this.
+
+`:scripts`:: Javascript scripts for HTML output. Defaults to built in scripts. Recommend against overriding this.
+
+`:wordstylesheet`:: Primary SCSS stylesheet to use for Word output. Defaults to built in stylesheet,
+which adheres with ISO formatting requirements. Recommend against overriding this.
+
+`:standardstylesheet`:: Secondary SCSS stylesheet use for Word output. Defaults to built in stylesheet,
+which adheres with ISO formatting requirements. Recommend against overriding this.
+
+`:header`:: Header and footer file for Word output. Defaults to built in template. Recommend against overriding this.
+
+`:wordcoverpage`:: Word template for cover page. Defaults to built in template. Recommend against overriding this.
+
+`:wordintropage`:: Word template for introductory section. Defaults to built in template. Recommend against overriding this.
+
+`:ulstyle`:: Word CSS selector for unordered lists in supplied stylesheets. Defaults to value for built in stylesheet. Recommend against overriding this.
+
+`:olstyle`:: Word CSS selector for ordered lists in supplied stylesheets. Defaults to value for built in stylesheet. Recommend against overriding this.
+
+
+The attribute `:draft:`, if present, includes review notes in the XML output;
+these are otherwise suppressed.
+
+The document proper can reference the values of document attributes, which is convenient
+for reusability. For example,
+the Rice Model document references the editorial groups that have contributed to the 
+document as
+
+[source,asciidoc]
+--
+This document was prepared by Technical Committee ISO/TC {technical-committee-number}, _{technical-committee}_, Subcommittee SC {subcommittee-number}, _{subcommittee}_.
+--
+
+If the corresponding document attributes are not populated in the header, then the references
+themselves will not be populated.
+
+
+== Data Models
+
+The IsoDoc data model (IsoStandardDocument) is instantiated from the
+https://github.com/riboseinc/isodoc-models[StandardDocument model]. For details
+please visit that page.
+
+== Code Structure
+
+The gem invokes the following other gems as a division of labour.
+
+* This gem generates the IsoDoc XML proper
+* https://github.com/riboseinc/isodoc renders IsoDoc XML into HTML
+* https://github.com/riboseinc/html2doc converts HTML into Microsoft Word
+* https://github.com/riboseinc/isodoc-models derives the ISO Standard grammar
+used for validation from the generic IsoDoc grammar
+
+
+== Examples
+
+The gem has been tested to date against the
+https://www.iso.org/publication/PUB100407.html["Rice document"], the ISO's
+model document of an international standard. Sample representation of the Rice document
+in Asciidoctor, and output formats, are included in the https://github.com/riboseinc/isodoc-rice
+repository.
+
+See also `link:spec/metanorma-iso[]` for individual features.