metanorma-iso 1.0.0

data/Rakefile

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

data/asciidoctor-iso.gemspec.old

@@ -0,0 +1,50 @@
+# coding: utf-8
+
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "asciidoctor/iso/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "asciidoctor-iso"
+  spec.version       = Asciidoctor::ISO::VERSION
+  spec.authors       = ["Ribose Inc."]
+  spec.email         = ["open.source@ribose.com"]
+
+  spec.summary       = "asciidoctor-iso lets you write ISO standards "\
+    "in AsciiDoc."
+  spec.description   = <<~DESCRIPTION
+    asciidoctor-iso lets you write ISO standards in AsciiDoc syntax.
+
+    This gem is in active development.
+  DESCRIPTION
+
+  spec.homepage      = "https://github.com/riboseinc/asciidoctor-iso"
+  spec.license       = "BSD-2-Clause"
+  spec.post_install_message = "The asciidoctor-iso gem has been deprecated and has been replaced by metanorma-iso"
+
+  spec.bindir        = "bin"
+  spec.require_paths = ["lib"]
+  spec.files         = `git ls-files`.split("\n")
+  spec.test_files    = `git ls-files -- {spec}/*`.split("\n")
+  spec.required_ruby_version = Gem::Requirement.new(">= 2.3.0")
+
+  spec.add_dependency "asciidoctor", "~> 1.5.7"
+  spec.add_dependency "ruby-jing"
+  spec.add_dependency "isodoc", "~> 0.8.8"
+  spec.add_dependency "iev", "~> 0.2.0"
+  spec.add_dependency "relaton", "~> 0.1.3"
+  spec.add_dependency "metanorma-standoc", "~> 0.0.1"
+
+  spec.add_development_dependency "bundler", "~> 1.15"
+  spec.add_development_dependency "byebug"
+  spec.add_development_dependency "equivalent-xml", "~> 0.6"
+  spec.add_development_dependency "guard", "~> 2.14"
+  spec.add_development_dependency "guard-rspec", "~> 4.7"
+  spec.add_development_dependency "rake", "~> 12.0"
+  spec.add_development_dependency "rspec", "~> 3.6"
+  spec.add_development_dependency "rubocop", "~> 0.50"
+  spec.add_development_dependency "simplecov", "~> 0.15"
+  spec.add_development_dependency "timecop", "~> 0.9"
+  spec.add_development_dependency "metanorma", "~> 0.2.6"
+  spec.add_development_dependency "isobib", "~> 0.2.0"
+end

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/docs/customisation.adoc

@@ -0,0 +1,186 @@
+= Gem Customisation Guide
+
+In this guide, we give advice on how to adopt the Metanorma approach to document generation for your documents. We provide enough guidance for you to do full customisation, but we prefix each section with a Tip for quick-and-dirty implementation.
+
+== How can I adopt the StanDoc specification for my own publications?
+
+TIP: Copy the RSD schema from https://github.com/riboseinc/metanorma-iso/blob/master/grammars/rsd.rng. You may need to adapt some of the enums in the model, or in the ISO Standards model that it inherits; but in the first instance, you can just ignore the differences—and ignore the validation feedback that the toolset gives.
+
+The Standoc specification is expressed in http://www.relaxng.org[RelaxNG schema for XML], and is intended to be customisable for different types of publication. The customisation of Standoc relies on inheritance, with the following schemas embedded hierarchically:
+
+* https://github.com/riboseinc/bib-models[Relaton]: bibliography
+* https://github.com/riboseinc/basicdoc-models[BasicDoc]: block-level and inline formatting
+* https://github.com/riboseinc/metanorma-standoc[StanDoc]: organisation of sections for a generic standards document
+* Models specific to standards
+
+Because of the richness of the ISO standards model, most Standoc standards to date (including the sample gem https://github.com/riboseinc/metanorma-sample) inherit from the ISO Standards model, which itself inherits from Standoc.
+
+Specialisation of a model consists of:
+
+* Adding classes to a base model.
+* Changing attributes of a base model class. This is not restricted to adding attributes, as is the case in typical entity subclassing; it can also include removing attributes from a class, changing their obligation and cardinality, and changing their type, including changing enumerations. Attributes can be overruled at any level; for example, standards-specific models routinely enhance the bibliographic model at the base of the hierarchy.
+* For reasons of clarity, renaming classes and attributes is avoided in specialisation.
+
+To adapt the schema for your publication set,
+
+* Get familiar with the Standoc set of models, and identify any elements that you would want to represent differently for your documents (different types, different enums), or enhance for your documents (additional element attributes, additional elements)
+* Create a grammar inheriting from StanDoc or from a specific standard, which expresses what is distinctive about your grammar.
+** We recommend starting your modelling in UML, as an effective communication tool; compare the UML models for Standoc standards at https://github.com/riboseinc/metanorma-iso
+** The tool suite expects to validate against a set of schemas expressed in RelaxNG. We have been authoring grammars in RelaxNG Compact, as a more human-readable format, then compiling those grammars to RelaxNG using https://github.com/relaxng/jing-trang[jing-trang]. You can choose to use a different schema language, but you will need to customise the tool chain to validate against that form of schema instead.
+** In order to make schema inheritance easier, we have avoided using namespaces for the individual schemas; a namespace is added to the standards-specific schema at the very end of the inheritance chain.
+
+== How can I adapt the StanDoc toolchain for my own publications?
+
+[TIP]
+====
+The easiest way to adopt StanDoc is to use the metanorma-acme gem: https://github.com/riboseinc/metanorma-acme, supplying your own stylesheets and HTML files for styling.
+
+If you wish to create a custom gem, in order to customise behaviour further:
+
+* Clone the metanorma-sample gem: https://github.com/riboseinc/metanorma-sample.
+* Change the namespace for RSD documents (`RSD_NAMESPACE = "https://open.ribose.com/standards/rsd"`) to a namespace specific to your organisation's document standard.
+* Change any references to `sample` or `Sample` in the gem to your organisation's document standard.
+* Change the styling of the document outputs (`.../lib/isodoc/XXX/html`).
+====
+
+The tool chains currently available proceed in two steps: map an input markup language (currently Asciidoctor only) into Standoc XML, and map Standoc XML into various output formats (currently Word doc, HTML, PDF via HTML). Running the metanorma tool involves a third step, of exposing the capabilities available in the first two in a consistent format. These two steps are represented as three separate modules, which are included in the same gem; for the Sample gem, they are `Asciidoctor::Sample`, `Isodoc::Sample`, and `Metanorma::Sample`. (In the case of Asciidoctor-ISO, almost all the content of `Isodoc::ISO` is in the isodoc gem, so the base classes of the two steps are in separate gems.) 
+
+Your adaptation of the toolchain will need to instantiate these three modules. The connection between the two first steps is taken care of in the toolchain, and metanorma explicitly invokes the two steps, feeding the XML output of the first step as input into the second. The metanorma-sample gem outputs both Word and HTML; you can choose to output only Word (as is done in metanorma-m3d), or only HTML (as is done in metanorma-csand), and you can choose to generate PDF from HTML as well (as is done in metanorma-csd).
+
+The modules involve classes which rely on inheritance from other classes; the current gems all use `Asciidoctor::ISO::Converter`, `Isodoc::{Metadata, HtmlConvert, WordConvert}`, and `Metanorma::Processor` as their base classes. This allows the standards-specific classes to be quite succinct, as most of their behaviour is inherited from other classes; but it also means that you need to be familiar with the underlying gems, in order to do most customisation.
+
+In the case of `Asciidoctor::X` classes, the changes you will need to make involve the intermediate XML representation of your document; e.g. adding different enums, or adding new elements. The adaptations in `Asciidoctor::Sample::Converter` are limited, and most projects can take them across as is: 
+
+* The boilerplate representation of the document's author, publisher and copyright holder names Ribose instead of ISO as the responsible organisation.
+* The editorial committees are represented as a single element, as opposed to ISO's name plus number.
+* The document title is monolingual, not bilingual.
+* The document status is a single element, as opposed to ISO's two-part code.
+* The document identifier is a single element.
+* Title validation and style validation is disabled.
+* The root element of the document is changed from `iso-standard` to `rsd-standard`.
+* The document type attribute is restricted to a prescribed set of options.
+* A `literal` element and a `keyword` element is added to the ISO instance of Standoc.
+* The inline headers of ISO are ignored.
+
+The customisations needed for Metanorma::Sample::Processor are minor:
+
+* `initialize` names the token by which Asciidoctor registers the standard
+* `output_formats` names the available output formats (including XML, which is inherited from the parent class)
+* `version` gives the current version string for the gem
+* `input_to_isodoc` is the call which converts Asciidoctor input into IsoDoc XML
+* `output` is the call which converts IsoDoc XML into various nominated output formats
+
+The customisations needed for Isodoc::Sample are more extensive. Three base classes are involved: 
+
+* `Isodoc::Metadata` processes the metadata about the document stored in `//bibdata`. This information typically ends up in the document title page, as opposed to the document body. For that reason, metadata is extracted into a hash, which is passed to document output (title page, Word header) via the https://shopify.github.io/liquid/[Liquid template language].
+* `Isodoc::HtmlConvert` converts Standoc XML to HTML.
+* `Isodoc::WordConvert` converts Standoc XML to Word HTML; the https://github.com/riboseinc/html2doc[html2doc] gem then converts this to a .doc document.
+
+The `Isodoc::HtmlConvert` and `Isodoc::WordConvert` overlap substantially, as both use variants of HTML; in fact the files `samplehtmlrender.rb` and `samplewordrender.rb` are deliberately identical, apart from the class their code belongs to. However there is no reason not to make substantially different rendering choices in the HTML and Word branches of the code.
+
+= How can I style the resulting HTML output?
+
+[TIP]
+====
+* Clone the metanorma-sample gem: https://github.com/riboseinc/metanorma-sample.
+* Edit the `html_sample_titlepage.html` and `html_sample_intro.html` pages to match your organisation's branding.
+** Leave the Liquid Template instructions alone (`{{`, `{%`) unless you know what you're doing with them: they are how the pages are populated with metadata.
+* Edit the `default_fonts()` method in your `IsoDoc::...::HtmlConvert` class, to match your desired fonts.
+* Edit the `default_file_locations()` method in your `IsoDoc::...::HtmlConvert` class, to match your desired stylesheets and HTML templates.
+* Edit the `htmlstyle.scss` stylesheet to match your organisation's branding. The classes already in place there are used to style existing blocks of text; refer to the sample documents included in the gem (`spec/examples`) for their use.
+====
+
+Styling of output is intended to be configurable. HTML stylesheets are expressed in https://sass-lang.com/guide[SCSS], with their fonts populated through the `default_fonts()` method in the `IsoDoc::...::HtmlConvert` class. Frontispiece content is templated, populated from metadata parsed in the `IsoDoc::...::Metadata` class, via https://shopify.github.io/liquid/[Liquid templates]. The default stylesheets and HTML templates themselves are nominated in the `default_file_locations()` method in the `IsoDoc::...::HtmlConvert` class. That means you can change the styling of output documents readily, so long as you are aware of the functionality of the stylesheet.
+
+* Styling information is stored in the `.../lib/isodoc/html` folder of the gem, and applies to both Word and HTML content. For HTML content, the relevant files are `html_..._titlepage.html` (title page HTML template), `html_..._intro.html` (introductory HTML template, typically restricted to Table of Contents), `scripts.html` (Javascript scripts), and `htmlstyle.scss` (the HTML stylesheet).
+* The styling files to be loaded in are set in the `default_file_locations()` method of `IsoDoc::...::HtmlConvert`. The files can be overridden through document variables in the Asciidoc document.
+* Additional files (e.g. logos) can be loaded in the `initialize()` method of `IsoDoc::...::HtmlConvert`; for them to be access during document generation, they need to be copied to the working directory. (They can be removed subsequently by adding them to the `@files_to_delete` array. All image files are copied into an `_html` subdirectory.)
+* The HTML templates are populated through Liquid Templates: variables in `{{` correspond to the hash keys for metadata extracted in `IsoDoc::...::Metadata`, and its superclass `IsoDoc::Metadata` in the isodoc gem.
+* The SCSS stylesheets treat fonts as variables. Those variables are set in `default_fonts()`, which generates variable assignments for SCSS. Stylesheets normally recognise three fonts: `$bodyfont` for body text, `$headerfont` for headers and captions (which may be the same font as `$bodyfont`), and `$monospacefont` for monospace text. Note that `default_fonts()` takes the options passed to initialise `HtmlConvert` as a paremeter; the document language and script can be used to make different font choices for different document scripts. (The existing gems refer to `Latn`, Latin script, and `Hans`, Simplified Chinese script.)
+* Javascript scripts are populated in `scripts.html`; the scripts already in place in any gem you modify are in live use, and you should work out what they do before removing them. The AnchorJS script, for example, is used to generate navigable anchors in the document.
+* Additional scripts and fonts may be loaded in the document head through the `html_head()` method of  `IsoDoc::...::HtmlConvert`. The existing gems use the document head to load Jquery, the Table of Contents generation script, Google Fonts, and Font Awesome.
+* An HTML document is populated as follows:
+** HTML Head wrapper (in `IsoDoc::HtmlConvert`)
+*** `html_head()` content
+*** `@htmlstylesheet` CSS stylesheet (expected to be in SCSS, generated from SCSS in the `generate_css()` method of `Isodoc::HtmlConvert`).
+** HTML Body
+*** `@htmlcoverpage` HTML template (optional, corresponds to `html_..._titlepage.html`)
+*** `@htmlintropage` HTML template (optional, corresponds to `html_..._intro.html`)
+*** Document proper (converted from Standoc XML)
+*** `@scripts` Javascript Scripts (optional, corresponds to `scripts.html`)
+* The classes in the SCSS stylesheet correspond to static HTML content in the HTML templates, and dynamic HTML content in the `IsoDoc::...::HtmlConvert` class, and its superclasses `IsoDoc::HtmlConvert` and `IsoDoc::Common` in the isodoc gem.
+
+= How can I style the resulting Word output?
+
+[TIP]
+====
+* There is no quick way of doing this.
+* Everything you can do in Word, you can do in Word HTML. Save Word documents as Word HTML to see how.
+* Clone the metanorma-sample gem: https://github.com/riboseinc/metanorma-sample.
+* Edit the `word_sample_titlepage.html` and `word_sample_intro.html` pages to match your organisation's branding. With lots of iterations of saving Word documents as HTML, for trial and error.
+** Leave the Liquid Template instructions alone (`{{`, `{%`) unless you know what you're doing with them: they are how the pages are populated with metadata.
+* Edit the `default_fonts()` method in your `IsoDoc::...::WordConvert` class, to match your desired fonts.
+* Edit the `default_file_locations()` method in your `IsoDoc::...::WordConvert` class, to match your desired stylesheets and file templates.
+* Edit the `wordstyle.scss` and `sample.scss` stylesheets to match your organisation's branding. With lots of iterations of saving Word documents as HTML, for trial and error.
+====
+
+Word output in the document toolset is generated through Word HTML, the variant of HTML that you get when you save a Word document as HTML. (That is why documents are saved in `.doc`, not `.docx`.) This has the advantage over https://en.wikipedia.org/wiki/Office_Open_XML[OOXML], the native markup of DOCX, of using a well-known markup language, with a low barrier to entry: if you want to work out how to do something in Word HTML, do it in Word, save the document as HTML, and open up the HTML in a text editor. (For more on the choice of using Word HTML, see https://github.com/riboseinc/html2doc/wiki/Why-not-docx%3F.)
+
+However Word HTML is not quite the HTML you are used to: it is a restricted, syntactically idiosyncratic variant of HTML 4, with a non-standard and weakened form of CSS. Doing any styling in Word HTML involves lots of trial and error, and paying close attention to how Word HTML does things in its CSS. We have documented a few of the clearer gotchas in https://github.com/riboseinc/html2doc/blob/master/README.adoc.
+
+It's still better than learning OOXML.
+
+The process for generating Word output is fairly similar to that for generating HTML, since both processes are generating a form of HTML; as we already noted, the two processes share a substantial amount of code. The main differences are in the handling of page-media features that CSS has lagged in (footnotes, pagination, headers and footers), and in the styling of lists, for which Word HTML uses custom (and undocumented) CSS classes prefixed with `@`, specifying inter alia the numbering for nine levels of nesting of the same list.
+
+* Styling information is stored in the `.../lib/isodoc/html` folder of the gem, and applies to both Word and HTML content. For Word content, the relevant files are `word_..._titlepage.html` (title page HTML template), `word_..._intro.html` (introductory HTML template, typically restricted to Table of Contents),  `wordstyle.scss` and `{name_of_standard}.scss` (the Word stylesheets), and `header.html` (document headers, footers, and endnote/footnote separators, referenced from the stylesheets).
+* The styling files to be loaded in are set in the `default_file_locations()` method of `IsoDoc::...::WordConvert`. 
+* As with HTML generation, additional files (e.g. logos) can be loaded in the `initialize()` method of `IsoDoc::...::WordConvert`. The `initialize()` method also sets the `@` styles in the stylesheet to be used for unordered and ordered lists; a single such style is intended to capture the behaviour of all levels of indentation. 
+* As with HTML output, the HTML templates are populated through Liquid Templates: variables in `{{` correspond to the hash keys for metadata extracted in `IsoDoc::...::Metadata`, and its superclass `IsoDoc::Metadata` in the isodoc gem.
+* As with HTML, the SCSS stylesheets treat fonts as variables, and are set in the `default_fonts()` method of `IsoDoc::...::WordConvert`.
+* Document headers and footers are set in the `header.html` file. This is also an HTML template, which is populated with metadata attributes through Liquid Template. The structure of `header.html` is determined by Word, and elements of `header.html` need to be crossreferenced from the Word stylesheet. To inspect Word `header.html` files, save a Word document as HTML, and look inside the `{document_name}.fld` folder generated alongside the HTML output.
+* A Word HTML document is populated as follows:
+** HTML Head wrapper (in `IsoDoc::WordConvert`)
+*** `@wordstylesheet` CSS stylesheet (generated from SCSS through the `generate_css()` method of `Isodoc::WordConvert`); corresponds to `wordstyle.scss`.
+*** `@standstylesheet` CSS stylesheet (generated from SCSS through the `generate_css()` method of `Isodoc::WordConvert`); intended to override any generic CSS in `@wordstylesheet`. Optional, corresponds to `{name_of_standard}.scss`.
+** HTML Body
+*** `@wordcoverpage` HTML template (optional, corresponds to `word_..._titlepage.html`). Included in `<div class=WordSection1>`.
+*** `@htmlintropage` HTML template (optional, corresponds to `word_..._intro.html`). Included in `<div class=WordSection2>`. In the existing gems, WordSection2 is paginated with roman numerals. 
+*** Document proper (converted from Standoc XML). Included in `<div class=WordSection2>` (prefatory material) and `<div class=WordSection3>` (main document). In the existing gems, WordSection3 is paginated with roman numerals.
+* The classes in the SCSS stylesheet correspond to static HTML content in the HTML templates, and dynamic HTML content in the `IsoDoc::...::WordConvert` class, and its superclasses `IsoDoc::WordConvert` and `IsoDoc::Common` in the isodoc gem.
+
+= How can I localize the resulting output?
+
+[TIP]
+====
+* Copy the `lib/isodoc/i18n-en.yaml` file from the isodoc gem to your gem.
+* Edit the right-hand text in the file.
+* Give the file location as the `i18nyaml` document attribute in any files you wish to use your localisation.
+====
+
+Every piece of text generated by the toolset instead of the author is looked up in an internationalisation file; that means that if the language setting for the document changes, and there is an internationalisation file for that language, all output is localised to that language. Of the existing gems, metanorma-gb is localised in this way for English and Chinese, and metanorma-iso is localised for English, French and Chinese. 
+
+The localisation files are http://yaml.org[YAML] files stores in `lib/isodoc/`, named `i18n-{languagecode}.yaml`. (In the case of Chinese, the script code is added to the filename: `i18n-zh-Hans.yaml`.) Most localised text are direct mappings from English metalanguage to the target language (including English itself); there are also instances of hashes in the YAML files. Most localisation text consists of one- or two-word labels, such as "Figure" or "Annex"; some boilerplate text is also included in the localisation text, such as the ISO text describing the use of external sources in Terms and Definitions.
+
+Localisation is mostly used for translation purposes, but they can also be used to customise the rendering of particular labels in English. For example, the default English label for a first-level supplementary section is "Annex", reflecting ISO practice; but in the metanorma-csd gem, this label is overruled in code to be "Appendix" instead.
+
+The YAML files are read into the `IsoDoc` classes through the `i18n_init()` method of `IsoDoc::...::HtmlConvert` and `Isodoc::...::WordConvert`. The localisation equivalents for the nominated language are read from the corresponding YAML file into the `@labels` hash. The base Isodoc instance of `i18n_init()` also assigns an instance variable for each label (e.g. `@annex_lbl` for English "Annex"). These instance variables are used to generate all automated text in the Isodoc classes.
+
+All current gems inherit their localisation files from the base isodoc gem. The local `i18n_init()` instance can overwrite individual labels in code (metanorma-csd), or they can read in a local additional YAML file for the same language (metanorma-gb). If you are implementing a completely new language, you will need to replace the base `i18n_init()` method rather than inheriting from it, to ensure that the local YAML files are read in.
+
+The foregoing describes how to incorporate localisation into your gem on a permanent basis; but the toolset also allows you to nominate a YAML localisation file just for the current document. In Asciidoc, the YAML file is nominated as the i18nyaml document attribute; for IsoDoc, it is passed in as the `i18nyaml` hash attribute to the initialisation method. You will still need to access the base IsoDoc YAML instances, to make sure that all necessary labels are given in your YAML document.
+
+= I can translate my specifications into IsoDoc XML myself (i.e. I don't like AsciiDoc, or I already have my own toolchain). Can I only use IsoDoc XML to produce pretty output?
+
+[TIP]
+====
+* Generate correct IsoDoc XML (make sure it validates!)
+* Create just the `IsoDoc::...::HtmlConvert` and/or `IsoDoc::...::WordConvert` classes to convert the IsoDoc XML into target formats.
+* Initialise the IsoDoc class passing the necessary information about fonts and scripts; the existing gems all illustrate this kind of initialisation.
+* Create the target format using the method `.convert(filename, xml)`.
+====
+
+The Asciidoctor-to-XML and XML-to-Output classes are separate, so you can invoke just the latter without the former. Of course, you will need to make sure that the IsoDoc XML you are passing to the generators is valid.
+
+The `IsoDoc::...::HtmlConvert` and/or `IsoDoc::...::WordConvert` are initialised in the existing gems with a hash giving the fonts to be used in the document (to be injected in the document SCSS stylesheets), the script of the document (to be used to pick the right font, in case of default font settings), and the `i18nyaml` YAML file for localisation. All existing gems have defaults set for these values on the Asciidoctor side invoking the class, so all parameters are optional.
+
+Once you have the classes set up, all you need to do is invoke the conversion of XML to the target format, with the method `.convert(filename, xml)`, where XML is the IsoDoc XML.

data/docs/guidance.adoc

@@ -0,0 +1,436 @@
+= Guidance for Authoring
+The Asciidoc approach to authoring ISO standards (and other related standards under Metanorma) is not https://en.wikipedia.org/wiki/WYSIWYG[WYSIWYG]: you are dealing with a text editor and a console rather than a Word document, and you are authoring something that looks more like HTML than the final product. On the other hand, editing documents with a markup system like Asciidoc makes it much easier to automate key validation and formatting processes, such as checking for missing document components, autonumbering, and generating output in multiple formats.
+
+The documents you will be authoring will be in the http://asciidoctor.org[Asciidoc] formatting language, so you need to be familiar with that language's markup conventions: the http://asciidoctor.org/docs/user-manual/[Asciidoctor User Manual] will be your companion (supplemented by the https://github.com/riboseinc/metanorma-iso#asciidoctor-model-additions[additions to markup made for ISO standards]. However we have tried to make things easier for you by preparing an https://github.com/riboseinc/metanorma-iso/blob/master/spec/examples/rice.adoc[AsciiDoc version] of the ISO Standard exemplar, the https://www.iso.org/publication/PUB100407.html["Rice document"]. If you use this document as a template for your own ISO standard document, you will find most of the formatting you need illustrated there.
+
+== Usage
+
+See the README on https://github.com/riboseinc/metanorma-iso#usage[how to deploy and use the gem].
+
+== Output in different languages
+
+The gem allows generation of standards in different languages; the language of the document is specified in the `:language:` document attribute (and `:script:`, for languages with more than one script).
+
+For each language, language-specific templated text is specified for the boilerplate, labels and cross-references that are included in document output. The gem has predefined templates for English, Chinese (Simplified) and French. You can specify your own language by providing your own http://www.yaml.org/spec/1.2/spec.html[YAML] template file, and linking to it with the `:i18nyaml` document attribute. The YAML template you provide needs to match https://github.com/riboseinc/isodoc/blob/master/lib/isodoc/i18n-en.yaml, substituting translations for each of the fields given.
+
+The Chinese (Simplified) template also localises punctuation and spacing, mapping them away from the default Latin punctuation used elsewhere in the gem.
+
+== Validation
+
+All AsciiISO documents that are processed by the Asciidoctor-ISO gem are validated against a formal schema for the document structure, as well as style rules around content. The gem will generate a sequence of warnings; you should pay attention to them. 
+
+The content warnings come first, and are prefixed with `ISO Style`. They try to impose rules on content taken from http://www.iec.ch/members_experts/refdocs/iec/isoiecdir-2%7Bed7.0%7Den.pdf[ISO/IEC DIR 2], including restrictions on where requirements may be stated, usage of decimal points, hanging clauses, and subclauses that are the only child of their parent clause. While the error detection is not infallible, they should be reviewed at least once. Where possible, the gem will give the ID or section heading associated with the error. For example:
+
+[source,console]
+--
+ISO style: WARNING (Section: ): Footnote may contain requirement: The maximum permissible mass fraction of defects shall be determined with respect to the mass fraction obtained after milling.
+ISO style: WARNING (Section: Wire sieve,): possible decimal point: 0.02
+ISO style: invalid technical committee type XYZ
+ISO style: AnnexA-4-1:Preparation of test sample: subsection is only child
+--
+
+The syntax errors come afterwards, and they report the line number and line position of the syntax error in the intermediate XML format generated by the gem. (For example, the AsciiDoc document `rice.adoc` generates the intermediate XML file `rice.xml`.) These errors deal with restrictions on what kinds of text can appear where, pointers within the document that are orphaned, and elements that appear in the wrong sequence. Deciphering what has gone wrong with them may take more effort, but the errors they point to are more serious than the style errors, and need to be resolved for the document to be well-formed. The gem will usually (but not always!) generate HTML and Word output despite the presence of those errors.
+
+For example:
+
+[source,console]
+--
+value of attribute "date" is invalid; must be an ISO date @ 454:183
+element "review" missing required attribute "from" @ 454:183
+element "subsection" not allowed here; expected the element end-tag or element "admonition", "dl", "example", "figure", "formula", "note", "ol", "p", "quote", "review", "sourcecode", "table" or "ul" @ 467:52
+value of attribute "date" is invalid; must be an ISO date @ 476:233
+IDREF "Annex-A-2" without matching ID @ 315:50
+IDREF "last_conformance_class" without matching ID @ 649:236
+IDREF "Annex-A" without matching ID @ 308:141
+--
+
+Currently validation only processes English-language text for language-specific rules (e.g. requirements); French validation is planned.
+
+The gem also validates terms cited from the IEV against the online IEV Electropedia entries: if the preferred term does not match the form given in the IEV for that entry, it will issue a warning.
+
+== Document header
+
+The core metadata about the standard comes from the Asciidoc document header (the list of colon-delimited attributes at the start of the document), and the https://github.com/riboseinc/metanorma-iso#document-attributes[README documents what those fields should be]. Use the Rice document as a template, and be careful about sticking to the guidelines on populating them.
+
+The Rice document contains some additional fields that are not essential to ISO rendering, and help Asciidoctor preview the document with its native renderer, should you so choose. (For example, `:appendix-caption: Annex` ensures that the native Asciidoctor renderer calls appendices Annexes; but the Word and HTML output of the gem will do so regardless of how this value is populated.) You will need to leave the `:stem:` field in if you have any AsciiMath or MathML to include in the document; otherwise they will not be detected.
+
+The document header, unlike the document proper, cannot deal with HTML entities. If you need to enter accented characters for the French title, or dashes for compound titles, you will need to enter them directly as Unicode (even if your console text editor doesn't like it): `:title-main-fr: Spécification et méthodes d'essai`, not `:title-main-fr: Sp\écification et m\éthodes d'essai`; `:title-part-en:Information Technology—Security`, not `:title-part-en:Information Technology\—Security`.
+
+== Document sections
+
+Sections are marked off in Asciidoc with titles prefixed by double equal signs, `==`. The gem depends on the titles given to identify the different kinds of sections in the document. As a result, you cannot choose to modify the titles of sections; the `Introduction`, `Scope`, `Normative References`, `Terms and Definitions`, `Symbols and Abbreviations`, and `Bibliography` need to be titled as such.
+
+The Foreword of an ISO standard is detected as any text between the document header and the first section header (the document preamble). The Rice document gives the `.Foreword` title to the preamble, but the gem will supply the "Foreword" title regardless of what title is present.
+
+In the Rice document, Asciidoctor section numbering is disabled for the Foreword and Introduction, and reenabled for the Scope. Again, the gem will number those sections correctly whatever the markup.
+
+
+=== Bibliographies
+
+The Normative References and the Bibliography must be preceded by the style attribute `[bibliography]`, so that the references they contain may be recognised as such. 
+
+All bibliographic entries must be given as unordered lists. 
+
+Currently the gem only supports formatted citations, which are given as such in the Asciidoc source. In the future, we expect to integrate the documents with http://www.bibtex.org[BibTex] databases, through the https://github.com/riboseinc/asciidoctor-bibliography[asciidoctor-bibliography] gem.
+
+==== ISO References
+
+For ISO and related standards, the entry must be preceded by a bibliographic anchor, in triple brackets: this consists of an internal identifier (used in citations), followed by the ISO identifier for the reference as its label. For example:
+
+[source,asciidoc]
+--
+* [[[ricepotentialmilling,ISO 6646]]], _Rice -- Determination of the potential milling yield from paddy and from husked rice_
+* [[[ISOGuide73, ISO Guide 73:2009]]], _Risk management -- Vocabulary_
+--
+
+[subs="quotes"]
+ISO 6646 is cited from elsewhere in the document through crossreferences to the `ricepotentialmilling` identifier; e.g. `<< ricepotentialmilling>>` (which will be rendered as `ISO 6646`), `<<``ricepotentialmilling, section 5``>>` (which will be rendered as `ISO 6646, Section 5`), `<<``ricepotentialmilling,section 5: the foregoing discussion``>>` (which will be tagged in the XML representation as Section 5 of ISO 6646, but will be displayed as `the foregoing discussion`.)
+
+If an ISO reference is in preparation, ISO/IEC DIR 2 dictates that details of the reference status be given as a footnote. In Asciidoc, this is done by giving the date as a double dash, and following the bibliographic anchor with a footnote macro:
+
+[source,asciidoc]
+--
+* [[[ISO16634,ISO 16634:--]]] footnote:[Under preparation. (Stage at the time of publication ISO/DIS 16634)], _Cereals, pulses, milled cereal products, oilseeds and animal feeding stuffs -- Determination of the total nitrogen content by combustion according to the Dumas principle and calculation of the crude protein content_
+--
+
+If an ISO reference includes all parts of the standard, that is indicated by appending `(all parts)` after the reference anchor:
+
+[source,asciidoc]
+--
+* [[[ISO16634,ISO 16634 (all parts)]]] _Cereals, pulses, milled cereal products, oilseeds and animal feeding stuffs -- Determination of the total nitrogen content by combustion according to the Dumas principle and calculation of the crude protein content_
+--
+
+
+In informative references, ISO references are still given with the same format of bibliographic anchor, and they are cited by ISO document code -- although they are displayed with an incrementing reference number in brackets instead. So
+
+[source,asciidoc]
+--
+[bibliography]
+== Bibliography 
+
+* [[[ISO3696,ISO 3696]]], _Water for analytical laboratory use -- Specification and test methods_
+--
+
+is displayed as:
+
+[quote]
+____
+*Bibliography*
+
+[1] ISO 3696, _Water for analytical laboratory use -- Specification and test methods_
+____
+
+==== ISO Reference Fetching
+
+If any bibliographic entry has a label prefixed with `ISO`, e.g. `[[` `[ricepotentialmilling,ISO 6646]` `]]`, the gem accesses the ISO website (via the `isobib` stem), and screenscrapes the details of that item. The screenscraped data overrides any content about the item provided in the document, since the ISO website is treated as the bibliographic source of truth on ISO documents.
+
+==== Non-ISO References
+
+In normative references, non-ISO documents must still be given a document code (or title) in their bibliographic anchor:
+
+[source,asciidoc]
+--
+* [[[RFC4291,IETC RFC 4193]]] _Unique Local IPc6 Unicast Addresses_, October 2005. http://www.ietf.org/rfc/rfc4291.txt
+* [[IANAMediaTypes,IANA Media Types Assignment]]], March 2017. http://www.iana.org/assignments/media-types/media-types.xthml
+--
+
+In informative references, non-ISO documents are both displayed and cited with reference numbers in brackets. Those numbers are given in the reference anchor instead of the ISO document code. ISO references appear before non-ISO references; the reference number is expected to be correct in context:
+
+[source,asciidoc]
+--
+* [[[IEC61010-2,IEC 61010-2:1998]]], _Safety requirements for electric equipment for measurement, control, and laboratory use -- Part 2: Particular requirements for laboratory equipment for the heating of material_
+
+* [[[ref10,10]]] [smallcap]#Standard No I.C.C 167#. _Determination of the protein content in cereal and cereal products for food and animal feeding stuffs according to the Dumas combustion method_ (see http://www.icc.or.at)
+--
+
+==== Cross-References
+
+Normally in Asciidoctor, any text in a cross-reference that follows a comma constitutes custom text for the cross-reference. So a cross-reference `<<ISO7301,the foregoing reference>>` will be rendered as "the foregoing reference", and hyperlinked to the ISO7301 reference.
+
+In AsciiISO cross-references, bibliographic localities (e.g. page numbers, clause numbers) can be added directly after the comma, as part of the cross-reference text: this overrides the normal Asciidoctor treatment of custom text. Bibliographic localities are expressed as a sequence of lowercase locality type, then an equal sign, then the locality value or range of values. The locality can appear in quotations, if it contains special characters (like dashes or commas).
+
+[source,asciidoctor]
+--
+<<ISO7301,clause=3.1-3.4>>
+
+NOTE: This table is based on <<ISO7301,table=1>>.
+
+Sampling shall be carried out in accordance with <<xxx,section="5-3-1,bis">>
+--
+
+Any text after the bibliographic localities is still treated as custom cross-reference text; e.g. `<<ISO7301,clause=5,table=1,the foregoing reference>>`. 
+
+Custom cross-references should not be used in ISO standards, either for an external reference, or for a section of the current document: ISO/IEC DIR 2 requires any cross-references to be transparent in text. For example, a cross-reference to the anchor `[[tabular]]` on clause 5 should be given as just `<<tabular>>`, without any custom text: it will be automatically rendered as `Clause 5` by the gem.
+
+ISO clause references in particular will suppress the word "Clause" before a subclause reference, following ISO/IEC DIR 2: `<``<ISO24333,clause=5>``>` will be rendered as _ISO 24333, Clause 5_, but `<``<ISO7301,clause=3.1>``>` will be rendered as _ISO 7301, 3.1_.
+
+
+=== Terms and Definitions
+
+The title of a top-level Terms and Definitions clause is populated automatically, overriding the title provided by the user: if it contains a Symbols and Abbreviated Terms subclause, it is titled _Terms, definitions, symbols and abbreviated terms_, otherwise it is titled _Terms and definitions_. A Terms and Definitions clause will be recognised if either title is given, regardless of case. Symbols and Abbreviated Terms subclauses are also automatically titled; other subclauses of Terms and Definitions clauses are not.
+
+If the Terms and Definitions are partly or fully sourced from another standard, that document is named as a `[source=REFERENCE]` attribute to the section. (The attribute needs to be applied to the top-level clause, if there are subclauses.) If there are no terms and definitions defined in this standard, no terms should be included in the section body (it should be blank). The boilerplate at the start of the section is adjusted to reflect both possibilities; any paragraphs or lists in the Asciidoctor input (which can replicate the expected boilerplate) is stripped in the intermediate XML format.
+
+Terms and Definitions sections follow a strict grammar, which is reflected in their Asciidoc markup:
+
+* The term is given as a subheading at the appropriate level (three equal signs, unless there are subsections in the Terms and Definition section). The term may be crossreferenced from other terms, in which case it should have an anchor.
+* The term is optionally followed by alternative/admitted terms, which must be marked up in an `+alt:[...]+` macro; deprecated terms, which must be marked up in a `+deprecated:[...]+` macro; and a term domain, which must be marked up in a `+domain:[...]+` macro.
+* The definition of the term is given in a separate paragraph.
+* The definition is optionally followed by examples (paragraphs with an `[example]` style attribute).
+* The definition is then optionally followed by notes (denoted with a `NOTE:` prefix).
+* The definition is then followed by a citation for the term, marked with a `[.source]` role attribute). 
+* The citation is a cross-reference to a normative reference, optionally followed by a comma and a modification if applicable.
+
+For example,
+
+[source,asciidoc]
+--
+[[paddy]]
+=== paddy 
+alt:[paddy rice]
+alt:[rough rice]
+deprecated:[cargo rice]
+domain:[rice]
+
+rice retaining its husk after threshing
+
+[example]
+Foreign seeds, husks, bran, sand, dust.
+
+NOTE: The starch of waxy rice consists almost entirely of amylopectin. The kernels have a tendency to stick together after cooking. 
+
+[.source]
+<<ISO7301,section 3.2>>, The term "cargo rice" is shown as deprecated,
+and Note 1 to entry is not included here
+--
+
+The requirement that the source of a term be given in a citation also applies when the source is a term bank, such as http://www.electropedia.org[IEV]. By ISO convention, IEV references are not included in the bibliography, but for consistency and validation purposes, the IEV should be cited as a normal reference, with the term given as a clause, and the source should be named as IEV in the bibliography. The XML encoding of the document will include the IEV reference, substituting a canonical form of the reference in the bibliography; the output rendering of the document will drop the reference from the bibliography. For example:
+
+[source,asciidoc]
+--
+[.source]
+<<ievtermbank,clause="103-01-02">>
+....
+
+[bibliography]
+* [[[ievtermbank,IEV]]], _IEV: Electropedia_
+// will be excluded from HTML and Word output. Will be replaced by a canonical reference in XML output.
+--
+
+Note that, for IEV entries to be validated, the IEV reference must be given as a Clause, and in quotes (otherwise the locality syntax would be interpreted as a range); so `<<ievtermbank,clause="103-01-02">>` for IEV 103-01-02.
+
+Asciidoc does not permit macros to be nested inside other macros; so the following markup, introducing a stem expression as an admitted term, is illegal. (The use of stem expressions as preferred terms is not a problem, because the macro appears as a header.)
+
+[source,asciidoc]
+--
+=== stem:[t_90] 
+alt:[stem:[t_A]]
+
+Time to launch.
+--
+
+However, the gem will treat any standalone paragraph in a term section, consisting of just a stem macro, as an admitted term:
+
+[source,asciidoc]
+--
+=== stem:[t_90] 
+
+stem:[t_A]
+
+Time to launch.
+--
+
+
+=== Symbols and Abbreviations
+
+Symbols and Abbreviations sections are expected to be simple definition lists (http://asciidoctor.org/docs/user-manual/#labeled-list["labelled lists"] in Asciidoc nomenclature). The gem takes care of sorting the symbols in the order prescribed by ISO/IEC DIR 2, provided the symbols are in AsciiMath; sorting MathML entries is not currently supported.
+
+=== Clauses
+
+Blank subclause headings can be given as `=== {blank}`. These are used when you want to give a subclause number for a new subclause, but without an associated header text. So e.g. in the Rice Model document,
+
+[source,asciidoc]
+--
+=== Physical and chemical characteristics 
+
+==== {blank}
+
+The mass fraction of moisture, determined in accordance with...
+--
+
+renders as 
+
+____
+*4.2. Physical and chemical characteristics*
+
+*4.2.1.*  The mass fraction of moisture, determined in accordance with...
+____
+
+
+Inline subclause headings (e.g. for test methods) are indicated by preceding the heading with the `[%inline-header]` option attribute. So in the Rice Model document,
+
+[source,asciidoc]
+--
+[%inline-header]
+==== Sieve, 
+
+with round perforations of diameter 1,4 mm.
+--
+
+renders as 
+
+____
+*A.2.1.1. Sieve,* with round perforations of diameter 1,4 mm.
+____
+
+
+Normative clauses are indicated with the attribute `[obligation=informative]`; they are normative by default.
+
+=== Annexes
+
+All annexes must be preceded by the style attribute `[appendix]`, in order to be recognised correctly. For ISO standards, annexes are treated as normative by default; if they are informative, they must additionally be tagged with an obligation of "informative" (so `[appendix, obligation= informative]`).
+
+Appendixes to annexes can occur, although they are not mentioned in ISO/IEC DIR 2; ISO/IEC DIR 1 features them. They are marked up as immediate subsections of annexes, and must be tagged with an option attribute of "appendix":
+
+[source,asciidoc]
+--
+[appendix]
+== Annex A
+Text
+
+[%appendix]
+=== Appendix 1
+Text
+--
+
+The numbering of annexes and appendices is automatic: do not insert "Annex A" or "Appendix 1" as part of the title. Annex and Appendix titles can be left blank, as with Clauses.
+
+== Text markup
+
+=== Mathematical formatting
+
+Mathematical formatting is done using the `[stem]` macro. Asciidoc supports http://asciimath.org[AsciiMath] and LaTeX natively (AsciiMath by default); as of this writing the gem only supports AsciiMath. AsciiMath is converted to Microsoft Word's OOML via MathML, using the https://github.com/asciidoctor/asciimath[AsciiMath] Ruby gem; the syntax of the Ruby gem may be at odds with the usual MathJax processor of AsciiMath. (We have found that the Ruby gem insists on numerators being bracketed.)
+
+=== Formulae
+
+Formulae are marked up as `[stem]` blocks. Any explanation of symbols in the formula is given as a "where" paragraph, followed by a definition list. For example:
+
+[source,asciidoc]
+--
+[[formulaA-1]]
+[stem]
+++++
+w = (m_D) / (m_s)
+++++
+
+where
+
+stem:[w]:: is the mass fraction of grains with a particular defect in the test sample;
+stem:[m_D]:: is the mass, in grams, of grains with that defect; 
+stem:[m_S]:: is the mass, in grams, of the test sample. 
+--
+
+=== Figures
+
+Like formulae, figures can be followed by a definition list for the variables used in the figure; the definition list is preceded by `+*Key*+`. For example:
+
+[source,asciidoc]
+--
+[[figureC-1]]
+.Typical gelatinization curve
+image::rice_images/rice_image2.png[]
+footnote:[The time stem:[t_90] was estimated to be 18,2 min for this example.]
+
+*Key*
+
+stem:[w]:: mass fraction of gelatinized kernels, expressed in per cent
+stem:[t]:: cooking time, expressed in minutes
+stem:[t_90]:: time required to gelatinize 90 % of the kernels
+P:: point of the curve corresponding to a cooking time of stem:[t_90]
+
+NOTE: These results are based on a study carried out on three different types of kernel.
+--
+
+Subfigures are entered by including images in an Asciidoc example:
+
+[source,asciidoc]
+--
+[[figureC-2]]
+.Stages of gelatinization
+====
+.Initial stages: No grains are fully gelatinized (ungelatinized starch granules are visible inside the kernels)
+image::rice_images/rice_image3_1.png[]
+
+.Intermediate stages: Some fully gelatinized kernels are visible
+image::rice_images/rice_image3_2.png[]
+
+.Final stages: All kernels are fully gelatinized
+image::rice_images/rice_image3_3.png[]
+
+====
+--
+
+=== Tables
+
+Asciidoc tables are quite powerful for a non-XML markup language, but we have had to add the option of multiple header rows (attribute `headerrows=n`), to deal with the complexity of ISO tables with labels, variables, and units lining up in the header.
+
+Asciidoc allows table cells to have footnotes (which the gem renders inside the table), and notes following the table (which the gem moves inside the table footer.) Table 1 in the Rice document illustrates a large range of table formatting options.
+
+=== Lists
+
+Unordered lists in Word are rendered with em-dashes instead of bullets, as preferred by ISO. Ordered lists in Word are rendered with their labels bracketed. (_a)_, _1)_, etc.) Ordered lists in both HTML and Word have their labels pre-configured, to align with ISO/IEC DIR 2: _a), b), c)_ for the first level, then _1), 2), 3)_ for the second level, then _i), ii), iii)_, then _A), B), C)_, then _I), II), III)_. The `type` attribute for ordered lists in Asciidoc, which allows the user to specify the label of an ordered list, is ignored.
+
+=== Footnotes
+
+Asciidoc supports only single-paragraph footnotes through its footnote macro (which can only contain a single line of text); this reflects a stylistic bias against digressive text by the Asciidoc creator, and will not change. At best, it can be worked around by introducing line breaks into the macro (see https://github.com/asciidoctor/asciidoctor.org/issues/599, http://discuss.asciidoctor.org/footnotes-with-paragraph-breaks-td4130.html).
+
+=== Notes
+
+Notes that are not at the end of a clause are folded into the preceding block, if that block is not delimited (so that the user could not choose to include or exclude a note): that is, notes are folded into a preceding paragraph, list, formula, or figure.
+
+=== Reviewer Notes
+
+We have introduced a mechanism in the gem to annotate arbitrary blocks of text, using Asciidoc sidebars and anchors for the beginning and end of the annotation; see https://github.com/riboseinc/metanorma-iso#reviewer-notes[discussion in the README].
+
+== Cross-references
+
+The gem follows the guidance given in ISO/IEC DIR 2 rigorously. In particular, if a formula, example, figure, list, list item or table is cross-referenced outside its (sub)clause, the clause containing the item is always given in the cross-reference, unless the item is being referenced in the same clause. In the case of notes, the containing clause is extended to containing example, figure or table.
+
+So for example, in the Rice model document, formula B-.1 is defined in Annex B.6, and is referenced in B.6 and B.7. In the PDF Rice model document, both instances are cited as "Formula (B.1)"; but the gem follows ISO/IEC DIR 2 in citing the former as "Formula (B.1)", but the latter as "B.6, Formula (B.1)".
+
+The label of the item cross-referenced, the use of brackets, and the containing reference are all taken care of by the gem; the document author needs only give the item identifier in the Asciidoc (e.g. `<<``formulaB-1``>>` generates either "Formula (B.1)" or "B.6, Formula (B.1)", depending on where in the document it occurs.)
+
+List items can be cross-referenced by inserting a bookmark at the very start of the list item:
+
+[source,asciidoc]
+--
+. Ordered list
+.. [[id]] This is the first list item
+... [[id]] This is a list sub-item
+--
+
+== Asciidoctor Tips
+
+As we have noted, the http://asciidoctor.org/docs/user-manual/[Asciidoctor User Manual] should be your companion when authoring any Asciidoc documents, including Asciidoc documents under Metanorma. There are some more specialised aspects of Asciidoctor markup, which you might need to dig deeper to find in the manual; we list some of them here.
+
+* A note or admonition can be made to span multiple paragraphs (including lists and tables), by making it a https://asciidoctor.org/docs/user-manual/#delimited-blocks[delimited block]:
+
+[source,asciidoc]
+--
+[NOTE]
+====
+This is a multi-paragraph note.
+
+It includes:
+
+* A list
+
+|===
+| And 
+
+| a table
+|===
+====
+--
+
+* https://asciidoctor.org/docs/user-manual/#using-attributes-set-assign-and-reference[Attribute references] can be used as template variables in a document: if your document contains the text `{foo}`, you can assign the value to be populated in `{foo}` by setting it as a document attribute in the Asciidoctor header: `:foo: this is the text to replace "foo"`. In the Rice Model document example, document attributes are used to provide the Subcommittee and Technical Committee names, which are populated as template entries in the document foreword.