metanorma-iso 1.0.6 → 1.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1d89d0e755c16c4261948825fea427ec2eb255f548a34a996f7263eea3fc0503
-  data.tar.gz: 75c0d94502690fef83157506796522f451d52f52672ece087485fdeb6bc090ed
+  metadata.gz: 42be35a908161b2b1c90252599c743ebc821ca814b948425cfd0e58c43b2fe35
+  data.tar.gz: 4962fcc892f8ce7ac514d227d36d499b0f1c2df44994073d44b9efb14b6346c8
 SHA512:
-  metadata.gz: 0cd85c2674397b24c5c6b27815474b8c8b11f52ab46fc133f652688428d20a2bb4c5b95128356c8d031755dec71939af22234070ecdf5f6693af50e48543a51b
-  data.tar.gz: 89193ce1d3fef951ab93006dd21d28f3132aca52c4f97d91f76fb18ee72a58daa3128273bca9154963b4c76430e720e0390d6c0c3108af1e492d93f483df47b5
+  metadata.gz: 48a0e630835efcbf208346515d28a879cdf155b3c02d1fe52f314b86e370de01884ff7dfa36fc89dca8cccf5ce08cb70fea433c67f879f46dcce75cf9a34a9cc
+  data.tar.gz: 1fce93f337ad4a87713e58be9d839b06d23bf4a58f45a288fd8d8203bdc17bb5eaa977714bd47cd218b73181ada19c599d73f185b76dde215dc7385b6b6e44ee

data/README.adoc

@@ -1,4 +1,4 @@
-= AsciiISO: Asciidoctor processor for ISO standards
+= Metanorma-ISO: Metanorma processor for ISO standards
 
 image:https://img.shields.io/gem/v/metanorma-iso.svg["Gem Version", link="https://rubygems.org/gems/metanorma-iso"]
 image:https://img.shields.io/travis/riboseinc/metanorma-iso/master.svg["Build Status", link="https://travis-ci.org/riboseinc/metanorma-iso"]
@@ -10,19 +10,12 @@ _Formerly known as_ `asciidoctor-iso`.
 
 == Functionality
 
-This gem processes http://asciidoctor.org/[Asciidoctor] documents following
-a template for generating ISO International Standards. The following
-outputs are generated.
+This gem processes Metanorma documents following a template for generating ISO
+International Standards. The following outputs are generated.
 
-* (Optional) An HTML preview generated directly from the Asciidoctor document,
-using native Asciidocot formatting. 
-** http://asciimath.org[AsciiMathML] is to be used for mathematical formatting.
-The gem uses the https://github.com/asciidoctor/asciimath[Ruby AsciiMath parser],
-which is syntactically stricter than the common MathJax processor;
-if you do not get expected results, try bracketting terms your in AsciiMathML
-expressions.
-* an XML representation of the document, intended as a document model for ISO
+* The XML representation of the document, intended as a document model for ISO
 International Standards. 
+
 * The XML representation is processed in turn to generate the following outputs
 as end deliverable ISO standard drafts.
 ** Microsoft Word output (`.doc`), following the style conventions of the 
@@ -30,10 +23,13 @@ https://www.iso.org/iso-templates.html[ISO Standard Microsoft Word template].
 ** HTML. For ISO, two HTML files are generated: the `.html` file follows ISO
 conventions in rendering, which looks very similar to the Word output, while
 the `-alt.html` file has richer styling.
-** PDF. Not supported for the ISO gem, but available for other other specification,
+** PDF. Not supported for the ISO gem, but available for other specifications,
 generated from the HTML file.
 
-This AsciiDoc syntax for writing ISO standards is hereby named "AsciiISO".
+The following input formats are supported:
+
+* http://asciidoctor.org/[Asciidoctor]
+(This AsciiDoc syntax for writing ISO standards is hereby named "AsciiISO".)
 
 This README provides an overview of the functionality of the gem; see also
 https://github.com/riboseinc/metanorma-iso/wiki/Guidance-for-authoring[Guidance for authoring]
@@ -41,6 +37,12 @@ ISO standards using the gem. The
 https://github.com/riboseinc/metanorma-iso/wiki/Quickstart-Guide[Quickstart guide]
 gives a summary overview.
 
+NOTE: http://asciimath.org[AsciiMathML] is used for mathematical formatting.
+The gem uses the https://github.com/asciidoctor/asciimath[Ruby AsciiMath parser],
+which is syntactically stricter than the common MathJax processor;
+if you do not get expected results, try bracketting terms your in AsciiMathML
+expressions.
+
 == Usage
 
 The preferred way to invoke this gem is via the `metanorma` script:
@@ -61,6 +63,7 @@ document.
 
 The gem then converts the XML into HTML and DOC.
 
+////
 The gem can also be invoked directly within asciidoctor, though this is deprecated:
 
 [source,console]
@@ -76,6 +79,7 @@ ignores the ISO-specific modifications to the markup:
 ----
 $ asciidoctor a.adoc  
 ----
+////
 
 === Installation
 
@@ -93,7 +97,7 @@ $ gem install metanorma-iso
 === Content Warnings
 
 The gem also realises several format
-checks as prescribed in ISO/IEC DIR 2: 2018, and warns the user about them in the
+checks as prescribed in ISO/IEC DIR 2:2018, and warns the user about them in the
 console:
 
 * Numbers with what looks like dots instead of commas for decimal points.
@@ -188,208 +192,7 @@ XML to break up paragraphs within a footnote.)
 [[model_additions]]
 == Asciidoctor model additions
 
-=== Section titles
-ISO has special section types: "Scope", "Normative References", "Terms and Definitions", "Symbols and Abbreviated Terms", "Bibliography". By default, these are identified in Asciidoc by using those titles. The gem allows you to override the title by using a `heading` attribute on the node, so that the actual title in your Asciidoc can be something different; that is useful, for example, if you are translating the document into different languages. So:
-
-[source,asciidoctor]
---
-[heading=scope]
-== 范围
---
-
-Note that both the XML population, and the isodoc gem will overwrite any supplied title. If you are translating ISO documents into other languages, you will still need access to versions of the metanorma-iso and isodoc gems in those languages.
-
-=== Obligation
-The obligation of sections (whether they are normative or informative) is indicated
-with the attribute "obligation". For most sections, this is fixed; for annexes and clauses, the
-default value of the obligation is "normative", and users need to set the obligation
-to "informative" as a section attribute.
-
-[source,asciidoctor]
---
-[[AnnexA]]
-[appendix,obligation=informative]
-== Determination of defects
---
-
-=== Term markup
-
-To ensure the structure of Terms and Definitions is captured accurately, the following
-macros are defined, and must be used to mark up their respective content:
-
-`alt:[TERM]`:: for alternative terms
-`deprecated:[TERM]`:: for deprecated terms
-`domain:[TERM]`:: for term domains
-
-The macro contents can contain their own markup.
-
-[source,asciidoctor]
---
-=== paddy 
-alt:[_paddy_ rice]
-deprecated:[#[smallcap]#cargo# rice]
-domain:[rice]
-
-_paddy_ (<<paddy>>) from which the husk only has been removed
---
-
-=== Terms and Definitions markup
-
-If the Terms and Definitions of a standard are partly or fully sourced from
-another standard, that standard is cited in a `source` attribute to the section,
-which is set to the reference anchor of the standard (given under the Normative
-Referencecs)..
-The boilerplate of the Terms and Definitions section is adjusted accordingly.
-
-[source,asciidoctor]
---
-[source=ISO712]
-== Terms and Definitions
---
-
-Multiple sources are allowed, and need to be quoted and comma-delimited:
-
-[source,asciidoctor]
---
-[source="ISO712,ISO24333"]
-== Terms and Definitions
---
-
-
-=== Paragraph alignment
-
-Alignment is defined as an attribute for paragraphs:
-
-[source,asciidoctor]
---
-[align=left]
-This paragraph is aligned left
-
-[align=right]
-This paragraph is aligned right
-
-[align=center]
-This paragraph is aligned center
-
-[align=justified]
-This paragraph is justified, which is the default
---
-
-=== Reviewer notes
-
-Reviewer notes are encoded as sidebars, and can be separated at a distance from the
-text they are annotating; the text they are annotating is indicated through anchors. 
-Reviewer notes are only rendered if the document has a `:draft:` attribute.
-
-The following attributes on reviewer notes are mandatory:
-
-* `reviewer` attribute (naming the reviewer) 
-* the starting target anchor of the note (`from` attribute)
-
-The following attributes are optional:
-
-* `date` attribute, optionally including the time (as xs:date or xs:datetime)
-* the ending target anchor of the note (`to` attribute)
-
-The span of text covered by the reviewer note is from the start of the
-text encompassed by the `from` element, to the end of the text encompassed
-by the `to` element. If only the `from` element supplied, the reviewer note
-covers the `from` element. The `from` and `to` elements can be bookmarks,
-which cover no space.
-
-[source,asciidoctor]
---
-[[clause_address_profile_definition]]
-=== Address Profile Definition (AddressProfileDescription)
-
-[[para1]]
-This is a clause address [[A]]profile[[B]] definition
-
-[reviewer="Nick Nicholas",date=20180125T0121,from=clause_address_profile_definition,to=para1]
-****
-I do not agree with this statement.
-****
-
-[reviewer="Nick Nicholas",date=20180125T0121,from=A,to=B]
-****
-Profile?!
-****
---
-
-=== Strikethrough and Small Caps
-
-The following formatting macros are used for strikethrough and small caps text:
-
-[source,asciidoctor]
---
-[strike]#strike through text#
-[smallcap]#small caps text#
---
-
-=== Count of table header and footer rows
-
-In Asciidoc, a table can have at most one header row or footer row. In ISO,
-a nominal single header row is routinely broken up into multiple rows in order
-to accommodate units or symbols, that line up against each other, though
-they are displayed as merged cells with no grid between them. To address this,
-tables can be marked up with an optional `headerrows` attribute:
-
-[source,asciidoctor]
---
-[headerrows=2]
-|===
-.2+|Defect 4+^| Maximum permissible mass fraction of defects in husked rice +
-stem:[w_max]
-| in husked rice | in milled rice (non-glutinous) | in husked parboiled rice | in milled parboiled rice
-
-| Extraneous matter: organic footnote:[Organic extraneous matter includes foreign seeds, husks, bran, parts of straw, etc.] | 1,0 | 0,5 | 1,0 | 0,5
-|===
---
-
-=== Inline clause numbers
-
-For some clauses (notably test methods), the clause heading appears inline with the clause, instead of being separated on a different line. This is indicated in Asciidoc by the option
-attribute `inline-header`:
-
-[source,asciidoctor]
---
-[%inline-header]
-[[AnnexA-2-1]]
-==== Sample divider, 
-
-consisting of a conical sample divider
---
-
-=== Bibliographic details
-
-Citations can include details of where in the document the citation is located; these
-are entered by suffixing the type of locality, then an equals sign, then the reference. 
-The word "whole" on its own is also treated as a locality. Multiple
-instances of locality and reference can be provided, delimited by comma or colon. Any trailing
-text after the sequence of locality=reference (or locality, space, reference) are treated
-as substitute text, as would occur normally in an Asciidoctor crossreference. For
-example:
-
-[source,asciidoctor]
---
-<<ISO712,the foregoing reference>>     # renders as: the foregoing reference
-<<ISO712,section=5, page 8-10>>         # renders as: ISO 712, Section 5, Page 8-10
-<<ISO712,section=5, page=8-10: 5:8-10>> # renders as ISO 712, 5:8-10 ("5:8-10" treated as replacement text for all the foregoing)
-<<ISO712,whole>>                        # renders as: ISO 712, Whole of text
---
-
-The references cannot contain spaces. Any text following the sequence of localities
-will be displayed instead of the localities.
-
-A custom locality can be entered by prefixing it with `locality:`:
-
-[source,asciidoctor]
---
-<<ISO712,locality:frontispiece=5, page=8-10>>         # renders as: ISO 712, Frontispiece 5, Page 8-10
---
-
-Custom localities may not contain commas, colons, or space. Localities with the `locality:`
-prefix are recognised in internationalisation configuration files.
+Refer also to https://github.com/riboseinc/metanorma-standoc/blob/master/README.adoc; this section lists additions specific only to metanorma-iso
 
 === Additional warning types
 
@@ -424,151 +227,8 @@ multiple-block warning
 ====
 --
 
-=== Block Quotes
-
-As in normal Asciidoctor, block quotes are preceded with an author and a citation;
-but the citation is expected to be in the same format as all other citations, 
-a cross-reference optionally followed by text, which may include the bibliographic
-sections referenced:
-
-[source,asciidoctor]
---
-[quote, ISO, "ISO7301,section 1"]
-_____
-This International Standard gives the minimum specifications for rice (_Oryza sativa_ L.) 
-which is subject to international trade. It is applicable to the following types: husked rice 
-and milled rice, parboiled or not, intended for direct human consumption. It is neither 
-applicable to other products derived from rice, nor to waxy rice (glutinous rice).
-_____
---
-
-=== Image size
-
-The value `auto` is accepted for image width and height attributes. It is only passed on
-to HTML output; if the output is to Word, both the width and height attributes are stripped
-from the image.
-
-[source,asciidoctor]
---
-[height=90,width=auto]
-image::logo.jpg
---
-
-=== Subclauses in Terms & Definitions sections
 
-Normally any terminal subclause in a Terms & Definitions section is treated as a term
-definition. Exceptionally, an introductory section can be tagged to be treated as a clause,
-instead of a term, by prefixing it with the style attribute `[.nonterm]`.
-
-[source,asciidoctor]
---
-== Terms and definitions
-
-[.nonterm]
-=== Introduction
-The following terms have non-normative effect, and should be ignored by the ametrical.
-
-=== Anapaest
-
-metrical foot consisting of a short, a long, and a short
---
-
-=== Sections embedded more than 5 levels
-
-Asciidoctor permits only 5 levels of section embedding (not counting the document title).
-Standards do contain more levels of embedding; ISO/IEC DIR 2 only considers it a problem
-if there are more than 7 levels of embedding. To realise higher levels of embedding,
-prefix a 5-level section title with the attribute `level=`:
-
-[source,asciidoctor]
---
-====== Clause 5
-
-[level=6]
-===== Clause 6
-
-[level=7]
-====== Clause 7A
-
-[level=7]
-====== Clause 7B
-
-[level=6]
-====== Clause 6B
-
-====== Clause 5B
---
-
-This generates the following ISO XML:
-
-[source,xml]
---
-<clause id="_" inline-header="false" obligation="normative">
-	<title>
-		Clause 5 
-	</title>
-	<clause id="_" inline-header="false" obligation="normative">
-		<title>
-			Clause 6 
-		</title>
-		<clause id="_" inline-header="false" obligation="normative">
-			<title>
-				Clause 7A 
-			</title>
-		</clause>
-		<clause id="_" inline-header="false" obligation="normative">
-			<title>
-				Clause 7B 
-			</title>
-		</clause>
-	</clause>
-	<clause id="_" inline-header="false" obligation="normative">
-		<title>
-			Clause 6B 
-		</title>
-	</clause>
-</clause>
-<clause id="_" inline-header="false" obligation="normative">
-	<title>
-		Clause 5B 
-	</title>
-</clause>
---
-
-=== PlantUML
-
-The http://plantuml.com[PlantUML] diagramming tool is integrated with Asciidoctor
-in this gem, as a literal block with the style attribute `plantuml`:
-
-[source,asciidoctor]
---
-[plantuml]
-....
-@startuml
-Alice -> Bob: Authentication Request
-Bob --> Alice: Authentication Response
-
-Alice -> Bob: Another authentication Request
-Alice <-- Bob: another authentication Response
-@enduml
-....
---
-
-The integration runs PlantUML for each such block, generating a PNG image.
-The images are stored in the `plantuml` directory, and linked into the output
-document in place of the PlantUML.
-
-PlantUML needs to be installed by users separately, and accesssible from the
-command line:
-
-* `brew install plantuml` on MacOS.
-* For Linux, link the PlantUML jar file into a command line executable; see
-`.travis.yml` for an example.
-
-If PlantUML is not installed locally, the source PlantUML is incorporated into
-the output document as sourcecode. 
-
-=== Features not visible in HTML preview
+== Features not visible in HTML preview
 
 The gem uses built-in Asciidoc formatting as much as possible, so that users
 can retain the ability to preview documents; for _Terms and Definitions_
@@ -691,7 +351,7 @@ The results of all `isobib` searches done to date for the current document
 (`filename.adoc`) are stored in the same directory as the current document,
 in the file `{filename}.relaton.pstore`. The local cache overrides entries in
 the global cache, and can be manually edited. The local cache is only used
-if the `:local-cache:` document attribute is set.
+if the `:local-cache:` or `:local-cache-only:` document attribute is set.
 
 If the document attribute `:no-isobib:` is set, the reference details for
 items are not looked up via `isobib`, and the `isobib` caches are not used.
@@ -730,6 +390,9 @@ ISO and IEV references online, but do not use the <<cache,cache>> of `isobib` an
 `:local-cache:`:: Use the local isobib and iev search caches to override the global isobib and iev search
 caches.
 
+`:local-cache-only:`:: Use the local isobib and iev search caches to the exclusion of the global isobib and iev search
+caches.
+
 `:i18nyaml:`:: Name of YAML file of internationalisation text, to use instead
 of the built-in English, French or Chinese text used to label parts of the document
 (e.g. "Table", "Foreword", boilerplate text for Normative References, etc.)
@@ -792,7 +455,8 @@ https://www.iso.org/stage-codes.html[International harmonized stage codes])
 in the deafting stage
 
 `:technical-committee-number:`:: The number of the relevant ISO technical
-committee
+committee (also `:technical-committee-number_2:`, `:technical-committee-number_3:`...;
+the same applies for all technical-committee, subcommittee and workgroup attributes)
 
 `:technical-committee-type:``:: The type of the relevant technical committee. Defaults
 to `TC` if not supplied. Values: `TC1, `PC`, `JTC`, `JPC`.
@@ -858,6 +522,7 @@ which adheres with ISO formatting requirements. Recommend against overriding thi
 
 `:olstyle`:: Word CSS selector for ordered lists in supplied stylesheets. Defaults to value for built in stylesheet. Recommend against overriding this.
 
+`:data-uri-image`:: Encode all images in HTML output as inline data-URIs.
 
 The attribute `:draft:`, if present, includes review notes in the XML output;
 these are otherwise suppressed.
@@ -902,3 +567,4 @@ in Asciidoctor, and output formats, are included in the https://github.com/ribos
 repository.
 
 See also `link:spec/metanorma-iso[]` for individual features.
+