metanorma-iso 1.0.0

data/docs/htmloutput.adoc

@@ -0,0 +1,115 @@
+= HTML and Word HTML Output
+
+In order to create CSS stylesheets for the HTML and Word HTML output of the Metanorma tool, it is necessary to understand the structure of the HTML it generates.
+
+== HTML
+
+=== Top-Level Structure
+
+The `head` of the HTML document contains a single stylesheet (the `:htmlstylesheet` parameter of `HtmlConvert.new()`), and some brief script calls that are embedded in the Ruby code (initialising jQuery, including webfonts).
+
+The `body` of the HTML document is divided into the following parts:
+
+* A title section (`<div class="title-section">`), comprising identifying information about the document, such as appears in a title page in print. 
+** The section is populated with an HTML template (the `:htmlcoverpage` parameter of `HtmlConvert.new()`). The information in this section is sourced from document metadata, rather than document content proper; the gem uses http://liquidmarkup.org[Liquid Template] to populate the HTML template. Different fields usually have distinct class names for CSS styling; these can vary by gem. 
+** For example, ISO documents have `coverpage_docnumber` (for the document ID), `coverpage_techcommittee` (for the technical committee responsible for the document), `doctitle-en` (for the English-language title of the document), `doctitle-fr` (for the French title), `title, subtitle, part` (for the three components of the document title), and `coverpage_docstage` (for the stage of publication of the document).
+* A prefatory section (`<div class="prefatory-section">`), comprising boilerplate information which also does not come from document content proper. This is typically restricted to a copyright statement (`<div class="copyright">`), contact details, and a table of contents `<div id="toc">`. 
+** The section is also populated with a Liquid HTML template (the `:htmlintropage` parameter of `HtmlConvert.new()`). 
+** The table of contents in the HTML template is a placeholder; it is populated by a table of contents script included among the scripts loaded into the HTML body.
+* The main section of the document (`<main class="main-section">`), which is populated with the document content.
+* Optionally, a colophon (`<div class="colophon">`), which is populated with boilerplate information and/or document metadata. (Currently colophons in Metanorma gems appear only in Word output.)
+* Scripts. These are populated from a static file (the `:scripts` parameter of `HtmlConvert.new()`). These are expected to include https://www.mathjax.org[MathJax], a Table of Contents generator, and a script for handling footnotes.
+
+=== Body markup
+
+Within the body of the document, different blocks and inline spans of the Metanorma document model (https://github.com/riboseinc/metanorma-model-standoc[Standoc XML], https://github.com/riboseinc/basicdoc-models[BasicDoc XML]) are represented by different CSS classes, as follows:
+
+==== Sections
+
+Symbols and abbreviated terms:: `<div class="Symbols">` (contents are a definition list)
+Appendix title:: `<h1 class="Annex">`
+Appendix, Bibliography, Introduction:: `<div class="Section3">`
+Introduction title:: `<h1 class="IntroTitle">`
+Foreword title:: `<h1 class="ForewordTitle">`
+Deprecated term:: `<p class="DeprecatedTerms">`
+Alternative term:: `<p class="AltTerms">`
+Primary term:: `<p class="Terms">`
+Term header:: `<p class="TermNum">`
+Document title (in body):: `<p class="zzSTDTitle1">`
+
+==== Blocks
+
+Note:: `<div class="Note">`
+Note label:: `<span class="note_label">`
+Figure:: `<div class="figure">`
+Figure title:: `<span class="FigureTitle">`
+Example:: `<table class="example">` or `<div class="example">`
+Example label:: `<span class="example_label">`
+Sourcecode:: `<p class="Sourcecode">`
+Admonition:: `<div class="Admonition">`
+Formula:: `<div class="formula">`
+Blockquote:: `<div class="Quote">`
+Blockquote attribution:: `<p class="QuoteAttribution">`
+Footnote:: `<aside class="footnote">`
+Ordered list:: `<ol>`
+Unordered list:: `<ul>`
+Definition list:: `<dl>`
+Normative reference:: `<p class="NormRef">`
+Informative reference:: `<p class="Biblio">`
+Table:: `<table>`
+Table title:: `<p class="TableTitle">`
+Table head:: `<thead>`
+Table body:: `<tbody>`
+Table foot:: `<tfoot>`
+
+==== Inline
+
+Hyperlink:: `<a>`
+Cross-Reference:: `<a>`
+Stem expression:: `<span class="stem">`
+Small caps:: `<span style="font-variant:small-caps;">`
+Emphasis:: `<i>`
+Strong:: `<b>`
+Superscript:: `<sup>`
+Subscript:: `<sub>`
+Monospace:: `<tt>`
+Strikethrough:: `<s>`
+Line Break:: `<br>`
+Horizontal Rule:: `<hr>`
+Page Break:: `<br>` (realised as page break in Word HTML)
+
+
+== Word HTML
+
+=== Word HTML and Word HTML CSS
+
+The Word HTML documented here is what is used by the gems to generate DOC output. For more on why Word HTML is used, instead of OOXML or HTML 5 embedded into DOCX, see https://github.com/riboseinc/html2doc/wiki/Why-not-docx%3F
+
+Word HTML, and the Word HTML version of CSS, are restricted compared to the HTML and CSS you are likely familiar with. Word HTML is a subset of HTML 4; Word HTML CSS has a weakened set of selectors, and a range of Microsoft-specific extensions (prefixed with `@` or `mso-`). The weakened set of selectors means you cannot assume that classes are inherited by their children; normal CSS would apply formatting on a `div` class to its child paragraphs, but Word HTML would expect you to repeat that class definition for `p`.
+
+Some of the necessary caveats are listed in https://github.com/riboseinc/html2doc/blob/master/README.adoc. The styling of lists in particular is quite different to normal CSS, and requires a Word-specific selector to define list styles (the `:ulstyle ` and `:olstyle ` parameter of `WordConvert.new()`).
+
+Word HTML and CSS is not well-documented (even though there is a 1500 page manual from Microsoft); fortunately saving Word documents to HTML will reveal the Word HTML and Word HTML CSS that can be used to generate the same formatting. The stylesheets need to follow the conventions of Word HTML, and should be formulated by saving Word documents as HTML, and extracting their CSS stylesheets. Note that the CSS is prefixed with a set of font definitions; these too should be obtained by saving Word documents as HTML.
+
+=== Top-Level Structure
+
+The headers and footers of a Word document are defined in Word HTML in a separate file, `header.html` (the `:header` parameter of `WordConvert.new()`), which is included in the file manifest for the document. The header.html file is cross-referenced to the Word HTML CSS file, and contains a separate `div` for each header and footer type; refer to the instances in the gems for illustration.
+
+The `head` of the Word HTML document contains two stylesheets (the `:wordstylesheet` and `:standardsheet` parameter of `WordConvert.new()`). The `:wordstylesheet` is intended as generic Word markup, while `:standardsheet` is intended to contain styling specific to the standard. No scripts are supported in Word HTML. 
+
+The other elements of the Word HTML head are populated by the https://github.com/riboseinc/html2doc[html2doc gem]: a reference to a manifest of included files (specifically images and the header file), and settings to open the document in Print View at 100% magnification.
+
+The `body` of the Word HTML document is divided into the following parts:
+
+* A title section (`<div class="WordSection1">`), comprising identifying information about the document, such as appears in a title page in print. 
+** The section is populated with an HTML template (the `:wordcoverpage` parameter of `WordConvert.new()`). As with HTML, the information in this section is sourced from document metadata, rather than document content proper; and the gem uses http://liquidmarkup.org[Liquid Template] to populate the HTML template. 
+* A prefatory section (`<div class="WordSection2">`), comprising boilerplate information which does not come from document content proper (such as a Table of Contents shell), as well as prefatory material from the document content. The prefatory section is set in the CSS stylesheet to have Roman numerals for its pagination.
+** Because of the requirement for Roman numerals, prefatory material from the document is sent to this section, whereas all document content in the HTML document is sent to the main section.
+* The main section of the document (`<div class="WordSection3">`), which is populated with the remaining document content. The main section is set in the CSS stylesheet to have Arabic numerals for its pagination.
+* Optionally, a colophon (`<div class="colophon">`), which is populated with boilerplate information and/or document metadata. 
+
+=== Body markup
+
+With the exception of the top-level document sections, discussed above, the Word HTML generated by the gem use the same CSS classes as the HTML proper. As already noted, the quirks of Word HTML CSS mean that classes need to be repeated on descendant elements that are not required in normal CSS.
+
+The handling of footnotes and comments in Word HTML uses idiosyncratic Word HTML markup, including custom CSS, and is generated separately their the HTML counterparts in the gems.

data/docs/quickstart.adoc

@@ -0,0 +1,375 @@
+= Quickstart Guide for AsciiISO
+
+This is a guide on how to get started using AsciiISO to create ISO standards documents compliant with 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"], in Microsoft Word and HTML formats.
+
+AsciiISO is the purposed-design syntax for creating ISO documents based on the AsciiDoc syntax.
+
+AsciiISO is currently used as input to the Asciidoctor-ISO renderer, which produces the corresponding https://github.com/riboseinc/isodoc-models[ISOXML schema] (in `.xml`), which in turn uses the https://github.com/riboseinc/isodoc[isodoc] gem to convert ISOXML into the final output formats, HTML (`.html`) and Word Document (`.doc`).
+
+
+== Even quicker summary
+
+In order to start a new ISO document, or migrate your document from Word:
+
+. Install <<installation>>
+. Clone the https://github.com/riboseinc/isodoc-rice/[AsciiISO Rice]
+
+To migrate:
+
+. Use our https://github.com/riboseinc/reverse_asciidoctor[reverse_asciidoctor] gem to help you convert a Word document into AsciiISO. That said, the conversion will not be 100% clean and you will have to manually fix some syntax (especially if your Word document contains an index, stray anchors, and equations).
+. Move the content back to the cloned isodoc-rice.
+
+
+[[installation]]
+== Installation instructions
+
+The Asciidoctor-ISO tool is a https://en.wikipedia.org/wiki/RubyGems[Ruby gem], and works on the command line. The https://en.wikipedia.org/wiki/Ruby_programming_language[Ruby programming language] can be installed on Windows (e.g. https://rubyinstaller.org), but is typically run on a Unix command line—including Linux and MacOS. The following instructions are for the Unix console.
+
+Asciidoctor-ISO in turn builds on the https://asciidoctor.org[Asciidoctor gem], which interprets the Asciidoctor markup language in Ruby. Installing the Asciidoctor-ISO gem will install the Asciidoctor gem, if it is not already installed.
+
+Ruby comes with Linux and MacOS. Asciidoctor-ISO uses Ruby 2.4.0, and you may need to update your Ruby instance to use that version. Refer to https://www.ruby-lang.org/en/documentation/installation/
+
+You can install the Asciidoctor-ISO gem, and all its dependencies, through the Ruby gem installer:
+
+[source,console]
+--
+gem install metanorma-iso
+--
+
+If you want the latest version of the gem (which is still heavily under development), you can install it from Github:
+
+[source,console]
+--
+git clone https://github.com/riboseinc/metanorma-iso.git
+cd metanorma-iso
+gem build *.gemspec
+gem install *.gem
+--
+
+== How to set up a new project
+
+At its simplest, all you need is a text document in Asciidoctor format, which you compile using the Asciidoctor-ISO gem. To keep document dependencies in order, you should keep your document in a distinct folder:
+
+[source,console]
+--
+mkdir new_standard
+cd new_standard
+vi new_standard.adoc
+--
+
+To compile the document, execute the `asciidoctor` script, flagging it to use the ISO variant:
+
+[source,console]
+--
+asciidoctor --trace -b iso -r 'metanorma-iso' new_standard.adoc
+--
+
+NOTE: This command syntax will be changed soon.
+
+This will generate two files from the `new_standard.adoc` document (provided it is well-formed!): `new_standard.html` is a standalone HTML document, and `new_standard.doc` is a Word document (currently in the pre-2007 `.doc` format, but Microsoft Word will open it fine). Both these files are generated via an intermediate XML file, `new_standard.xml`, which represents the structure of the document following the rules of ISO/IEC DIR 2, as captured in the https://github.com/riboseinc/isodoc-models[ISOXML schema].
+
+Even if there are no errors in the Asciidoctor syntax, the document may still raise warnings to the console as it is being validated. The validation comes from ISO/IEC DIR 2, and consists of two parts: warnings about document content (e.g. requiring space before a percentage sign; requiring that the scope not contain text that looks like a recommendation); and warnings about document structure. The latter are generated by running the generated XML against the ISOXML schema, and report the line numbers of the XML document where issues are observed.
+
+=== Template
+
+To author Asciidoctor documents, you need to be familiar with the Asciidoctor syntax, as well as the Asciidoctor-ISO extensions to the syntax and conventions. The https://asciidoctor.org/docs/user-manual/[Asciidoctor User Manual] documents Asciidoctor itself; the https://github.com/riboseinc/metanorma-iso/wiki/Guidance-for-authoring[Guidance for Authoring in Asciidoctor-ISO] and the https://github.com/riboseinc/metanorma-iso/blob/master/README.adoc[Asciidoctor-ISO Readme] are the complete documentation for the ISO-specific extensions. But the simplest way to get started is to take a ready-made Asciidoctor-ISO document, and edit it, observing how it approaches various formatting tasks.
+
+The https://www.iso.org/publication/PUB100407.html["Rice document"] is the ISO's model document of an international standard. An Asciidoctor-ISO version of the document is available at https://github.com/riboseinc/isodoc-rice/ . We suggest downloading the site, and editing it.
+
+The `iso-rice-en.adoc` document consists of a document header, and it references the separate `body/body-en.adoc` document for the document proper (`include::body/body-en.adoc[]`). You can just continue on with the document text after the document header—so long as you remember to leave a blank line between the two.
+
+== AsciiDoc syntax supported
+
+The Rice document illustrates almost the full range of formatting available via Asciidoctor; Annex E (which is not in the original) illustrates features not demonstrated in the original document.
+
+Syntax includes the following; the links are to the Asciidoctor User Manual. All examples are taken from the Asciidoctor-ISO Rice document.
+
+=== https://asciidoctor.org/docs/user-manual/#doc-header[Document header]
+
+Attributes of the document, which typically appear in the coverpage (if at all), rather than in the document proper. The permitted attributes for Asciidoctor-ISO, and their expected values, are documented in the https://github.com/riboseinc/metanorma-iso#document-attributes[Asciidoctor-ISO Readme]. Note that the author line expected in Asciidoctor is not used; the title line is likewise ignored, in favour of attributes describing the three-part bilingual title.
+
+[source,asciidoctor]
+--
+= Rice model
+:docnumber: 17301
+:tc-docnumber: 17301
+:ref-docnumber: ISO 17301-1:2016(E)
+...
+--
+
+=== Inline formatting
+
+* https://asciidoctor.org/docs/user-manual/#text-formatting[Formatting marks]: bold, italic, monospace, subscript, superscript
+
+[source,asciidoctor]
+--
+This document specifies minimum requirements and test methods for rice (_Oryza sativa L._).
+--
+
+* https://asciidoctor.org/docs/user-manual/#anchordef[Anchors] (for internal cross-references): these can be defined for any section or subsection, and any block (e.g. images, lists, examples, formulas, and so forth). The numbering of all blocks and clauses is automated, and does not need to be provided in the text.
+* https://asciidoctor.org/docs/user-manual/#internal-cross-references[Internal Cross-references] reference anchors within the document. By default, the text for these is also automated, to follow ISO/IEC DIR 2, including naming the container of a block where required (e.g. `B.6, Formula (B.1)` for a formula in an annex). However, cross-references can supply their own text as an override, following a comma (e.g. `<``<AnnexB,the following annex>``>`).
+
+[source,asciidoctor]
+--
+The International Organization for Standardization (ISO) draws attention to the fact that it is claimed that compliance with this document may involve the use of a patent concerning sample dividers given in <<AnnexA>> and shown in <<figureA-1>>.
+
+...
+[[figureA-1]]
+.Split-it-right sample divider
+image::images/rice_image1.png[]
+--
+
+* https://asciidoctor.org/docs/user-manual/#url[URLs]
+
+[source,asciidoctor]
+--
+http://www.iso.org/obp[OBP]
+--
+
+* https://asciidoctor.org/docs/user-manual/#activating-stem-support[STEM support] (mathematical expressions), as both inline and block formatting. (ISO Formulae are expressed as stem blocks.) Asciidoctor natively uses http://asciimath.org[AsciiMath] for its mathematical expressions; the `:stem:` document attribute must be present for AsciiMath to be recognised. The gem will ensure that any AsciiMath is rendered in the HTML output, and converted to Microsoft Office's OOXML (via MathML) in the Word output. Asciidoctor also supports LaTeX, but the gem does not cater for converting LaTeX to a Word-compatible output.
+
+[source,asciidoctor]
+--
+[[formulaA-1,A.1]]
+[stem]
+++++
+w = (m_D) / (m_s)
+++++
+
+where
+
+stem:[w]:: is the mass fraction of grains with a particular defect in the test sample;
+--
+
+* https://asciidoctor.org/docs/user-manual/#user-footnotes[Footnotes]. Note that footnotes are treated as inline formatting, so they cannot straightforwardly span more than a single paragraph in Asciidoctor. Footnotes within figures and tables are rendered within their blocks, as required by ISO/IEC DIR 2.
+
+[source,asciidoctor]
+--
+containing a mass fraction of 4,1 % iodine and 6,3 % potassium iodide in deionized water such as Lugols.footnote:[Lugols is an example of a suitable product available commercially. This information is given for the convenience of users of this document and does not constitute an endorsement by ISO of this product.]
+--
+
+=== Blocks
+
+Blocks are groupings of paragraphs and text into larger units, commonly https://asciidoctor.org/docs/user-manual/#delimited-blocks[delimited], and optionally including a https://asciidoctor.org/docs/user-manual/#title[title] and https://asciidoctor.org/docs/user-manual/#metadata-2[metadata].
+
+* https://asciidoctor.org/docs/user-manual/#unordered-lists[Unordered lists]
+
+[source,asciidoctor]
+--
+The main changes compared to the previous edition are:
+
+* updated normative references;
+* deletion of 4.3.
+--
+
+* https://asciidoctor.org/docs/user-manual/#ordered-lists[Ordered lists]. Note that ISO/IEC presupposes that the first level of an ordered list is indexed with a lowercase letter. The gem automatically creates labels for the nested levels of ordered lists, and ignores any https://asciidoctor.org/docs/user-manual/#numbering-styles[numbering styles] indicated by the user.
+
+[source,asciidoctor]
+--
+. the sampling method used;
+. the test method used;
+. the test result(s) obtained or, if the repeatability has been checked, the final quoted result obtained;
+--
+
+* https://asciidoctor.org/docs/user-manual/#labeled-list[Definition lists]. These are used for all keys of figures and formulae, and as the content of Symbols and Abbreviations clauses and subclauses:
+
+[source,asciidoctor]
+--
+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.
+--
+
+Note that the key to a figure must be preceded by the paragraph `*Key*`, and the key to a formula must be preceded by the paragraph `where`.
+
+* https://asciidoctor.org/docs/user-manual/#tables[Tables]. Asciidoctor supports a rich range of table formatting (which the Asciidoctor-ISO gem extends further).
+
+[source,asciidoctor]
+--
+[[tableD-1]]
+[cols="<,^,^,^,^",headerrows=2]
+.Repeatability and reproducibility of husked rice yield
+|===
+.2+| Description 4+| Rice sample
+| Arborio | Drago footnote:[Parboiled rice.] | Balilla | Thaibonnet
+
+| Number of laboratories retained after eliminating outliers | 13 | 11 | 13 | 13
+| Mean value, g/100 g | 81,2 | 82,0 | 81,8 | 77,7
+|===
+--
+
+* https://asciidoctor.org/docs/user-manual/#images[Images], which are mapped to ISO figures, with accompanying titles:
+
+[source,asciidoctor]
+--
+[[figureC-1]]
+.Typical gelatinization curve
+image::images/rice_image2.png[]
+footnote:[The time stem:[t_90] was estimated to be 18,2 min for this example.]
+--
+
+* https://asciidoctor.org/docs/user-manual/#admonition[Admonitions], which express Notes, Warnings, Cautions, etc.
+
+[source,asciidoctor]
+--
+CAUTION: Only use paddy or parboiled rice for the determination of husked rice yield.
+--
+
+* https://asciidoctor.org/docs/user-manual/#prose-excerpts-quotes-and-verses[Block quotes]
+
+[source,asciidoctor]
+--
+[quote, ISO, "ISO7301,clause 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).
+_____
+--
+
+
+* https://asciidoctor.org/docs/user-manual/#example[Examples]
+* https://asciidoctor.org/docs/user-manual/#listing-blocks[Listing blocks] (source code), including https://asciidoctor.org/docs/user-manual/#callouts[source code callouts]
+
+[source,asciidoctor]
+----
+.Sample Code
+====
+
+[source,ruby]
+--
+puts "Hello, world."
+%w{a b c}.each do |x| <1>
+  puts x
+end
+--
+<1> This is an annotation
+====
+----
+
+* https://asciidoctor.org/docs/user-manual/#comments[Comments] (which are *not* rendered in the output)
+
+[source,ruby]
+--
+// all terms and defs references are dated
+--
+
+=== Sections
+
+* The Asciidoctor https://asciidoctor.org/docs/user-manual/#doc-preamble[Document preamble] is treated as the document Foreword: it is the text appearing between the document header and the first section header. (Note that the foreword is here given a https://asciidoctor.org/docs/user-manual/#title[block title], but that will be provided automatically anyway.)
+
+[source,asciidoctor]
+--
+[[foreword]]
+.Foreword
+ISO (the International Organization for Standardization)
+--
+
+* The Asciidoctor https://asciidoctor.org/docs/user-manual/#sections[Sections] correspond to ISO clauses, starting with the Introduction (if present). Each section and subsection is delimited with a header; the number of equal signs before the header indicate the level of nesting of the section, starting with two equal signs. No numbering should be given for any header: numbering is done automatically by the gem.
+
+[source,asciidoctor]
+--
+== Sampling
+Sampling shall be carried out in accordance with <<ISO24333,clause 5>>
+
+== Test methods
+
+=== Moisture content
+
+Determine the mass fraction of moisture in accordance with the method specified in <<ISO712>>.
+...
+
+--
+
+
+== Asciidoctor-ISO specific syntax
+
+Full details of Asciidoctor-ISO–specific markup and conventions is given in the https://github.com/riboseinc/metanorma-iso/blob/master/README.adoc[Asciidoctor-ISO Readme] and the https://github.com/riboseinc/metanorma-iso/wiki/Guidance-for-authoring[Guidance for authoring].
+
+https://asciidoctor.org/docs/user-manual/#section-styles[Section styles] are used to indicate specific types of section: `[bibliography]` for Normative References and Bibliography, `[appendix]` for Annexes, and `[%appendix]` for Appendixes (annexes of annexes). These styles must be provided for the sections to be processed correctly: bibliographic references will not be recognised as such, for example, without the `[bibliography]` style applied:
+
+[source,asciidoctor]
+--
+[bibliography]
+== Bibliography
+
+* [[[ISO3696,ISO 3696]]], _Water for analytical laboratory use -- Specification and test methods_
+--
+
+The sections that have a fixed position according to ISO/IEC DIR 2 (Introduction, Scope, Normative References, Terms and Definitions, Symbols and Abbreviations, Bibliography) need to be titled as such, as first-level headings.
+
+=== Terms and Definitions
+
+Terms and Definitions sections follow a strict grammar in their Asciidoctor-ISO markup, as ISO/IEC DIR 2 prescribes their structure so strictly. The following illustrates the complete structure of a term entry; the Rice document splits up these features among several terms.
+
+[source,asciidoctor]
+--
+[[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
+--
+
+Term banks such as the http://www.electropedia.org[IEV] must be treated like any other document, with terms treated as clauses; e.g. `<<IEV,clause 103-01-01>>`. The IEV by ISO convention will be left out of the output rendering of ISO standards.
+
+=== References (Normative, Informative)
+
+All bibliographic entries must be given as unordered lists. Normative references are expected to include only ISO and related standards; informative references may include any source.
+
+For ISO and related standards, the reference is given as a bibliographic anchor (in triple brackets), consisting of an internal identifier followed by the ISO identifier. The internal identifier can be used in cross-references (citations). The date may be added to the ISO identifier, as required by ISO/IEC DIR 2; standards under preparation have their date given as `--`, and should be accompanied by a footnote detailing the status of the standard.
+
+[source,asciidoctor]
+--
+Grade 3 quality as specified in <<ISO3696>>.
+
+...
+
+* [[[ISO3696,ISO 3696]]], _Water for analytical laboratory use -- Specification and test methods_
+* [[[ISO7301,ISO 7301:2011]]], _Rice -- Specification_
+* [[[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_
+--
+
+Non-ISO references under normative references are still cited by document identifier. Under informative references, non-ISO documents are both displayed and cited with reference numbers in brackets. In Asciidoctor-ISO, the cross-reference is a normal anchor identifier; the bracket numbering for informative references is automatic.
+
+[source,asciidoctor]
+--
+For details concerning the use of the Dumas method, see References <<ref10>> and <<ref16>>.
+
+...
+
+* [[[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)
+
+* [[[ref16,16]]] [smallcap]#Tkachuk R.# Nitrogen-to-protein conversion factors for cereals and oilseed meals. _Cereal Chem._ 1969, *46* (4) pp 419-423
+--
+
+In cross-references, bibliographic localities (e.g. page numbers, clause numbers) can be added directly after the comma, as part of the cross-reference text. Bibliographic localities are expressed as a sequence of lowercase locality type, then an equal sign, then by the locality number or range:
+
+[source,asciidoctor]
+--
+<<ISO7301,clause=3.1>>
+
+NOTE: This table is based on <<ISO7301,table=1>>.
+
+Sampling shall be carried out in accordance with <<ISO24333,clause=5>>
+--
+
+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_.
+
+
+=== Annexes
+
+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]`).
+
+The numbering of annexes and appendices is automatic: do not insert "Annex A" or "Appendix 1" as part of the title.
+