metanorma-standoc 2.1.1 → 2.1.2

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: metanorma-standoc
 version: !ruby/object:Gem::Version
-  version: 2.1.1
+  version: 2.1.2
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-05-16 00:00:00.000000000 Z
+date: 2022-06-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: asciidoctor
@@ -266,16 +266,16 @@ dependencies:
   name: metanorma-iso
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 2.1.2
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 2.1.2
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -413,7 +413,6 @@ files:
 - README.adoc
 - Rakefile
 - bin/rspec
-- docs/quickstart.adoc
 - lib/asciidoctor/standoc/base.rb
 - lib/asciidoctor/standoc/blocks.rb
 - lib/asciidoctor/standoc/blocks_notes.rb
@@ -661,7 +660,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.9
+rubygems_version: 3.3.7
 signing_key:
 specification_version: 4
 summary: metanorma-standoc realises standards following the Metanorma standoc model

data/docs/quickstart.adoc

@@ -1,375 +0,0 @@
-= 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/metanorma/metanorma-model-standoc[Metanorma schema] (in `.xml`), which in turn uses the https://github.com/metanorma/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/metanorma/isodoc-rice/[AsciiISO Rice]
-
-To migrate:
-
-. Use our https://github.com/metanorma/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 asciidoctor-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/metanorma/metanorma-iso.git
-cd asciidoctor-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 'asciidoctor-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/metanorma/metanorma-model-standoc[Metanorma 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/metanorma/metanorma-iso/wiki/Guidance-for-authoring[Guidance for Authoring in Asciidoctor-ISO] and the https://github.com/metanorma/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/metanorma/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/metanorma/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,asciidoc]
---
-= 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,asciidoc]
---
-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,asciidoc]
---
-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,asciidoc]
---
-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,asciidoc]
---
-[[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,asciidoc]
---
-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,asciidoc]
---
-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,asciidoc]
---
-. 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,asciidoc]
---
-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,asciidoc]
---
-[[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,asciidoc]
---
-[[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,asciidoc]
---
-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,asciidoc]
---
-[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,asciidoc]
-----
-.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,asciidoc]
---
-[[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,asciidoc]
---
-== 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/metanorma/metanorma-iso/blob/master/README.adoc[Asciidoctor-ISO Readme] and the https://github.com/metanorma/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,asciidoc]
---
-[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,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
---
-
-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,asciidoc]
---
-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,asciidoc]
---
-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,asciidoc]
---
-<<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.
-