metanorma-csd 1.0.11 → 1.0.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cfa77e6bb51c1c9b88c27780e2c2469d07a8a677dce69b429c90bf5a9e8935ad
-  data.tar.gz: ac9a4b4d45310c4dc67d5c9f4cf8f5ab16c400557bcc87181d8d373e07faca7b
+  metadata.gz: 11d60940512345545644ab6c55d0f71310ca12257b86ab7c9d1ca550d92bd414
+  data.tar.gz: 8808b89e1b47ac413aad8ceacc91929d32cad01dafeaddf179f69a846db0039b
 SHA512:
-  metadata.gz: 0b53a3f7c310eac3fd0eb622e04f828b54f6be4f92513eb5614eac743007c94479bdfae7fa3d63d62466f56498f3b3c28b2756ab6aebd06542133029d4423635
-  data.tar.gz: 4c0e567f10f0f0e76a75cd4724908d62be56ae7daf9e8ae4c7f681afa475faed3eb09b668db7e260d49c4e8365c2572c5d77678f4e54079a866af44b1bcaf63f
+  metadata.gz: 833eb87552db7ffe68cf48e96e7e6b2469c874efc091e1e311b009ee0cc7afeb988e640b377aef15cb0a4218dc2359eb45366ef8abcde26ac819aa940fbc3ee0
+  data.tar.gz: 941ac1ba05c88f284445263acb33b7eb6f499ad6916b7cd35388742d835989a2cffc61a5d0babaf4d42163e02d3542b199cdd12d97fe7c6d420bf0a9294cd207

data/docs/navigation.adoc

@@ -0,0 +1,8 @@
+---
+sections:
+- name: Introduction
+  items:
+    - quickstart
+---
+
+= Navigation

data/docs/quickstart.adoc

@@ -0,0 +1,368 @@
+= Quickstart Guide for Metanorma-CSD
+
+Start using Metanorma-CSD to author CalConnect docs in these steps:
+
+. Get Metanorma running on your machine
+. Fetch and compile an example Metanorma-CSD document
+. Modify the document to fit your goals while keeping it valid AsciiCSD
+
+This guide assumes proficiency with the terminal,
+and uses the Docker option of running Metanorma
+(there’re other
+https://www.metanorma.com/overview/getting-started/[options of installing Metanorma],
+too).
+
+
+== Get Metanorma running on your machine
+
+Assuming you have Docker installed, it’s as easy as:
+
+[source,console]
+--
+docker pull ribose/metanorma
+--
+
+
+== Fetch and compile an example Metanorma-CSD document
+
+We’re going to use the vCard Format Specification sample document here.
+Clone the Metanorma-CSD repository and change into the directory with the example:
+
+[source,console]
+--
+git clone https://github.com/riboseinc/metanorma-csd.git
+cd /spec/examples/
+--
+
+To compile the document, run the Docker container as follows:
+
+[source,console]
+--
+docker run -v "$(pwd)":/metanorma/ -w /metanorma ribose/metanorma "metanorma -t csd -x xml,html,pdf,doc rfc6350.adoc"
+--
+
+NOTE: If you use Metanorma-CLI instead of Docker,
+http://metanorma.com:4001/software/metanorma-cli/docs/usage/[see how to use the metanorma executable to compile documnts].
+
+
+== Write valid AsciiCSD
+
+A Metanorma-CSD is a file in AsciiDoc format with certain extensions
+specific to Metanorma as a whole and Metanorma-CSD in particular.
+(We call the format AsciiCSD for short.)
+
+
+=== AsciiDoc basics
+
+NOTE: Skip this section if you’re already familiar with AsciiDoc syntax.
+
+==== Inline formatting
+
+[source,asciidoc]
+--
+*bold emphasis*, _italic emphasis_, `monospace / code snippet`
+"`Typographic double quotes`", '`typographic single quotes`'
+Subscript: H~2~O; superscript: E=mc^2^
+--
+
+==== Sections, anchors and references
+
+[source,asciidoc]
+--
+== Section 1
+
+Content (see <<anchor>>)
+
+== Section 2
+
+=== Section 2.1
+
+[[anchor]]
+==== Section 2.2
+
+Content 2.2. http://www.calconnect.org/[CalConnect]
+--
+
+==== Lists and blocks
+
+[source,asciidoc]
+--
+* Unordered list item 1
+* Unordered list item 2
+
+. Ordered list item 1
+. Ordered list item 2
+
+Definition list:
+
+stem:[w]:: is the mass fraction of grains with defects in the test sample;
+stem:[m_D]:: is the mass, in grams, of grains with that defect;
+mag:: is the mass, in grams, of the aggregated test sample.
+--
+
+==== Tables, figures, footnotes
+
+A rather complex table:
+
+[source,adoc]
+----
+[[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
+|===
+----
+
+Images (figures) and footnotes:
+
+[source,adoc]
+----
+[[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.]
+----
+
+
+==== Admonition blocks, quotes & code listings
+
+Admonitions (notes, warnings, cautions, etc.) and examples:
+
+[source,adoc]
+----
+NOTE: It is unnecessary to compare rice yield across years.
+
+[example]
+5 + 3 = 8
+----
+
+Block quotes:
+
+[source,adoc]
+----
+[quote,ISO,"ISO7301,clause 1"]
+_____
+This Standard gives the minimum specifications for rice (_Oryza sativa_ L.)
+_____
+----
+
+Source code:
+
+[source,adoc]
+----
+[source,some-lang]
+------
+function () -> {}
+------
+----
+
+
+=== Extensions to AsciiDoc
+
+==== Document header & custom AsciiDoc attributes
+
+`:docnumber:`: CalConnect document number, as allocated by TCC.
+
+`:status:`: The status of the document can be one of:
+
+* proposal
+* working-draft
+* committee-draft
+* draft-standard
+* final-draft
+* published
+* withdrawn
+
+`:doctype:`: The type of the document can be one of:
+
+* standard
+* directive
+* guide
+* specification
+* report
+* amendment
+* technical-corrigendum
+
+`:technical-committee:`, `:technical-committee_N:` (where N is a positive integer):
+Technical committee; there can be more than one.
+
+`:draft:`: Enables comments in Word and XML.
+
+`:local-cache-only:`: Used with Metanorma under Docker to ensure bibliographic entries
+do not get unnecessarily fetched all the time.
+
+
+==== Foreword & Introduction
+
+Foreword must be put before the first real section/clause (the `==` one).
+
+----
+[[foreword]]
+.Foreword
+The Calendaring and Scheduling Consortium ("`CalConnect`") is global non-profit
+organization with the aim to facilitate interoperability of technologies across
+user-centric systems and applications...
+----
+
+Introduction comes after Foreword and is unnumbered (actually "`0`"):
+
+----
+[[introduction]]
+:sectnums!:     <== disables display of section number
+== Introduction
+
+<<ISO8601>> has been the international standard for date and time representations
+and is applied widely, including in the <<RFC5545>> and <<RFC6350>> standards
+...
+
+:sectnums:      <== re-enables display of section number
+----
+
+NOTE: Some ISO standards display Introduction section numbers (the "`0`") if there are
+too many sub-sections.
+
+
+==== Normative references & bibliography
+
+What is a normative vs informative reference?
+
+* A change to a normative reference requires updating of the document;
+* A change to an informative reference should not trigger a change in the document.
+
+
+Clause 2 must be this:
+
+----
+[bibliography]
+== Normative references
+
+* [[[ISO3696,ISO 3696]]], _Water for analytical laboratory use -- Test methods_
+----
+
+Last section must be this:
+
+----
+[bibliography]
+== Bibliography
+
+* [[[ISO5609,ISO 5609]]], _Soil for laboratory analysis -- Test methods_
+----
+
+NOTE: the Bibliography is identical in usage with the IETF RFC section "`Informative references`".
+
+
+==== Citations
+
+In a CSD you often want to cite external or internal references.
+
+Internal:
+[source,adoc]
+----
+[[dog-food]]
+== Dog food
+
+Dogs love food, not only bones. Mine especially loves eating Oreo's.
+
+== Living with your dog
+
+My dog, Cookie, loves to eat cookies (see <<dog-food>>).
+
+----
+
+
+External (remember to add the reference!):
+
+[source,adoc]
+----
+The quality requirements on wheat are described in <<ISO7301>>.
+
+In particular, those for bread wheat (T. aestivum) are given in
+<<ISO7301,clause=5.6>>.
+----
+
+
+==== Terms and definitions
+
+This must be clause 3.
+
+[source,adoc]
+----
+[[tda]]                      <= anchor if you want it
+[source=ISO8601-1]           <= allows inheriting terms and definitions from
+another document
+== Terms, definitions, symbols and abbreviations   <= can combine T&D and S&A
+
+=== Terms and definitions    <= the real T&D clause
+
+[[term-explicit]]            <= anchor if you want it
+==== explicit form           <= term item
+
+date and time representation that uses designator symbols to delimit
+time scale components
+----
+
+
+==== Term entry in T&D
+
+The structure is strict; the following illustrates the complete structure of a term entry.
+
+In the term source (`[.source]`), all content after the reference and the "`comma`" is about "`modifications`" to the original definition.
+
+[source,adoc]
+----
+[[paddy]]                  <= anchor
+=== paddy                  <= term
+alt:[paddy rice]           <= alternative term
+alt:[rough rice]           <= second alternative
+deprecated:[cargo rice]    <= deprecated term
+domain:[rice]              <= domain
+
+rice retaining its husk after threshing  <= definition
+
+[example]              <= example
+Foreign seeds, husks, bran, sand, dust.
+
+NOTE: The starch of waxy rice consists almost entirely of amylopectin. <= note
+
+[.source]
+<<ISO7301,section 3.2>>, The term "cargo rice" is shown as deprecated, <= source
+and Note 1 to entry is not included here.
+----
+
+
+==== Term entry sourced from IEC Electropedia (IEV)
+
+In the `[.source]`, a termbase such as the IEC Electropedia ("`IEV`") can be used, such as:
+
+[source,adoc]
+----
+[.source]
+<<IEV,clause "113-01-01">>, the term "space-time" is further explained
+in a new Note 2 to entry.
+----
+
+References to the specific IEC 60500 documents (where IEV terms came
+from) are automatically added to the Bibliography.
+
+
+==== Annex
+
+Annexes have to be placed before the "`Bibliography`".
+
+[source,adoc]
+----
+[[AnnexA]]
+[appendix,subtype=informative]
+== Example date and time expressions, and representations
+...
+----
+
+
+== Where next?
+
+* https://www.metanorma.com/overview/[Learn more about Metanorma]

data/lib/asciidoctor/csd/converter.rb

@@ -56,15 +56,6 @@ module Asciidoctor
                         File.join(File.dirname(__FILE__), "csd.rng"))
       end
 
-      def literal(node)
-        noko do |xml|
-          xml.figure **id_attr(node) do |f|
-            figure_title(node, f)
-            f.pre node.lines.join("\n")
-          end
-        end
-      end
-
       def sections_cleanup(x)
         super
         x.xpath("//*[@inline-header]").each do |h|
@@ -87,30 +78,6 @@ module Asciidoctor
       def word_converter(node)
         IsoDoc::Csd::WordConvert.new(doc_extract_attributes(node))
       end
-
-      def inline_quoted(node)
-        noko do |xml|
-          case node.type
-          when :emphasis then xml.em node.text
-          when :strong then xml.strong node.text
-          when :monospaced then xml.tt node.text
-          when :double then xml << "\"#{node.text}\""
-          when :single then xml << "'#{node.text}'"
-          when :superscript then xml.sup node.text
-          when :subscript then xml.sub node.text
-          when :asciimath then stem_parse(node.text, xml)
-          else
-            case node.role
-            when "strike" then xml.strike node.text
-            when "smallcap" then xml.smallcap node.text
-            when "keyword" then xml.keyword node.text
-            else
-              xml << node.text
-            end
-          end
-        end.join
-      end
-
     end
   end
 end

data/lib/asciidoctor/csd/csd.rng

@@ -74,28 +74,6 @@
         </choice>
       </element>
     </define>
-    <!-- TextElement |= keyword -->
-    <define name="TextElement">
-      <choice>
-        <text/>
-        <ref name="em"/>
-        <ref name="eref"/>
-        <ref name="strong"/>
-        <ref name="stem"/>
-        <ref name="sub"/>
-        <ref name="sup"/>
-        <ref name="tt"/>
-        <ref name="strike"/>
-        <ref name="smallcap"/>
-        <ref name="xref"/>
-        <ref name="br"/>
-        <ref name="hyperlink"/>
-        <ref name="hr"/>
-        <ref name="pagebreak"/>
-        <ref name="bookmark"/>
-        <ref name="keyword"/>
-      </choice>
-    </define>
     <define name="BibItemType">
       <choice>
         <value>directive</value>
@@ -288,16 +266,6 @@
       </element>
     </define>
   </include>
-  <define name="pre">
-    <element name="pre">
-      <text/>
-    </element>
-  </define>
-  <define name="keyword">
-    <element name="keyword">
-      <text/>
-    </element>
-  </define>
   <define name="csd-standard">
     <element name="csd-standard">
       <ref name="bibdata"/>

data/lib/asciidoctor/csd/isodoc.rng

@@ -384,6 +384,7 @@
       <ref name="sourcecode"/>
       <ref name="example"/>
       <ref name="review"/>
+      <ref name="pre"/>
     </choice>
   </define>
   <define name="paragraph">
@@ -540,6 +541,20 @@
       </zeroOrMore>
     </element>
   </define>
+  <define name="pre">
+    <element name="pre">
+      <attribute name="id">
+        <data type="ID"/>
+      </attribute>
+      <optional>
+        <ref name="tname"/>
+      </optional>
+      <text/>
+      <zeroOrMore>
+        <ref name="note"/>
+      </zeroOrMore>
+    </element>
+  </define>
   <define name="table">
     <element name="table">
       <attribute name="id">
@@ -710,6 +725,7 @@
       </optional>
       <choice>
         <ref name="image"/>
+        <ref name="pre"/>
         <zeroOrMore>
           <ref name="figure"/>
         </zeroOrMore>
@@ -735,6 +751,7 @@
       <ref name="sub"/>
       <ref name="sup"/>
       <ref name="tt"/>
+      <ref name="keyword"/>
       <ref name="strike"/>
       <ref name="smallcap"/>
       <ref name="xref"/>
@@ -765,6 +782,11 @@
       <text/>
     </element>
   </define>
+  <define name="keyword">
+    <element name="keyword">
+      <text/>
+    </element>
+  </define>
   <define name="sub">
     <element name="sub">
       <text/>

data/lib/isodoc/csd/html/html_csd_titlepage.html

@@ -37,12 +37,12 @@
     <span>TC {{ tc }}</span>
   </div>
 
-  {% if editors %}
+  {% if editors.size > 0 %}
   <div class="coverpage-tc-name">
     <span>Editors: {{ editors | join: ", " }}</span>
   </div>
   {% endif %}
-  {% if authors %}
+  {% if authors.size > 0 %}
   <div class="coverpage-tc-name">
     <span>Authors: {{ authors | join: ", " }}</span>
   </div>

data/lib/isodoc/csd/html_convert.rb

@@ -42,10 +42,6 @@ module IsoDoc
         end
       end
 
-      def pre_parse(node, out)
-        out.pre node.text # content.gsub(/</, "&lt;").gsub(/>/, "&gt;")
-      end
-
       def term_defs_boilerplate(div, source, term, preface)
         if source.empty? && term.nil?
           div << @no_terms_boilerplate
@@ -59,18 +55,6 @@ module IsoDoc
         @annex_lbl = "Appendix"
       end
 
-      def error_parse(node, out)
-        # catch elements not defined in ISO
-        case node.name
-        when "pre"
-          pre_parse(node, out)
-        when "keyword"
-          out.span node.text, **{ class: "keyword" }
-        else
-          super
-        end
-      end
-
       def html_head()
         <<~HEAD.freeze
         <title>{{ doctitle }}</title>

data/lib/isodoc/csd/pdf_convert.rb

@@ -42,10 +42,6 @@ module IsoDoc
         end
       end
 
-      def pre_parse(node, out)
-        out.pre node.text # content.gsub(/</, "&lt;").gsub(/>/, "&gt;")
-      end
-
       def term_defs_boilerplate(div, source, term, preface)
         if source.empty? && term.nil?
           div << @no_terms_boilerplate
@@ -59,18 +55,6 @@ module IsoDoc
         @annex_lbl = "Appendix"
       end
 
-      def error_parse(node, out)
-        # catch elements not defined in ISO
-        case node.name
-        when "pre"
-          pre_parse(node, out)
-        when "keyword"
-          out.span node.text, **{ class: "keyword" }
-        else
-          super
-        end
-      end
-
       def html_head()
         <<~HEAD.freeze
         <title>{{ doctitle }}</title>

data/lib/isodoc/csd/word_convert.rb

@@ -45,10 +45,6 @@ module IsoDoc
         end
       end
 
-      def pre_parse(node, out)
-        out.pre node.text # content.gsub(/</, "&lt;").gsub(/>/, "&gt;")
-      end
-
       def term_defs_boilerplate(div, source, term, preface)
         if source.empty? && term.nil?
           div << @no_terms_boilerplate
@@ -62,18 +58,6 @@ module IsoDoc
         @annex_lbl = "Appendix"
       end
 
-      def error_parse(node, out)
-        # catch elements not defined in ISO
-        case node.name
-        when "pre"
-          pre_parse(node, out)
-        when "keyword"
-          out.span node.text, **{ class: "keyword" }
-        else
-          super
-        end
-      end
-
       def cleanup(docxml)
         super
         term_cleanup(docxml)

data/lib/metanorma/csd/version.rb

@@ -1,5 +1,5 @@
 module Metanorma
   module Csd
-    VERSION = "1.0.11"
+    VERSION = "1.0.12"
   end
 end

data/metanorma-csd.gemspec

@@ -37,7 +37,7 @@ Gem::Specification.new do |spec|
   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 "rubocop", "= 0.54.0"
   spec.add_development_dependency "simplecov", "~> 0.15"
   spec.add_development_dependency "timecop", "~> 0.9"
   spec.add_development_dependency "metanorma", "~> 0.3.0"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: metanorma-csd
 version: !ruby/object:Gem::Version
-  version: 1.0.11
+  version: 1.0.12
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-11-27 00:00:00.000000000 Z
+date: 2018-12-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: metanorma-standoc
@@ -140,16 +140,16 @@ dependencies:
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - '='
       - !ruby/object:Gem::Version
-        version: '0.50'
+        version: 0.54.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - '='
       - !ruby/object:Gem::Version
-        version: '0.50'
+        version: 0.54.0
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -217,6 +217,8 @@ files:
 - bin/console
 - bin/rspec
 - bin/setup
+- docs/navigation.adoc
+- docs/quickstart.adoc
 - lib/asciidoctor/csd.rb
 - lib/asciidoctor/csd/biblio.rng
 - lib/asciidoctor/csd/converter.rb