asciidoctor-iso 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 81628e6445230282af27ae6ee08a5b1662850618
-  data.tar.gz: 5ec3c5c6573556c7cf6cfb5ebcaa827d728db794
+  metadata.gz: 1214d438d3c226629a8fff96a4c26c21f20d5bba
+  data.tar.gz: b57913fafdf74be666b2bc5c4a865fb6ac0fc9bc
 SHA512:
-  metadata.gz: e79a67ec52c08f26beeda9eca31e38556832ed8eaaa000b42e05fbafc24a59cc96166b81d32b43264432a11e1087862a14fe30dc3ae241a60012bb9ad6f9137e
-  data.tar.gz: 7ee22285f177d6c466cbf7870a4f9e001eda32485a517625afb3df7c37d5f83e51cef712b77569f1bca21323e60a8017a7c02101c68080368956af4f2f7c644f
+  metadata.gz: c6fe48101588ebe48a5f8f5d5b6b9486d3cbc8f1616b49259773d17bee1179a9cb0362a7ca4920803f0c22dc9065955e964fc24a6e93e622a64acb064a6074e7
+  data.tar.gz: ef8a83afdfa714b47047e0b12b1aa6590308a6ca30c7d723960cb002708c33382e9dd53e37ecddf4ab0f52eb633e3626497fce6a8b6dd168db4ef682fe4a8ef3

data/.gitattributes

@@ -1,2 +1,4 @@
 rfc2629*.* linguist-vendored
 mathml2omml*.* linguist-vendored
+*.html linguist-vendored
+*.css linguist-vendored

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.4.3
+before_install: gem install bundler -v 1.16.1

data/Gemfile.lock

@@ -1,8 +1,8 @@
 GIT
   remote: https://github.com/riboseinc/html2doc.git
-  revision: 8a131b82eeecd0c27e4bde873f2ba16d425754d6
+  revision: 3eb26a6807a55abc4b2e35570601618568f12e07
   specs:
-    html2doc (0.6.0)
+    html2doc (0.6.2)
       asciimath
       htmlentities (~> 4.3.4)
       image_size
@@ -14,13 +14,14 @@ GIT
 
 GIT
   remote: https://github.com/riboseinc/isodoc.git
-  revision: 0818963410de3aeb880f263678c47dcadcfe9b50
+  revision: 4fe5f001024f5c1c659c68b6c61a6e54bcc8e444
   specs:
-    isodoc (0.4.0)
+    isodoc (0.5.0)
       asciimath
       html2doc
       htmlentities (~> 4.3.4)
       image_size
+      liquid
       mime-types
       nokogiri (= 1.8.1)
       ruby-xslt
@@ -52,7 +53,7 @@ GEM
     docile (1.1.5)
     equivalent-xml (0.6.0)
       nokogiri (>= 1.4.3)
-    ffi (1.9.21)
+    ffi (1.9.23)
     formatador (0.2.5)
     guard (2.14.2)
       formatador (>= 0.2.4)
@@ -71,6 +72,7 @@ GEM
     htmlentities (4.3.4)
     image_size (1.5.0)
     json (2.1.0)
+    liquid (4.0.0)
     listen (3.1.5)
       rb-fsevent (~> 0.9, >= 0.9.4)
       rb-inotify (~> 0.9, >= 0.9.7)
@@ -89,15 +91,15 @@ GEM
       shellany (~> 0.0)
     optout (0.0.2)
     parallel (1.12.1)
-    parser (2.4.0.2)
-      ast (~> 2.3)
+    parser (2.5.0.3)
+      ast (~> 2.4.0)
     powerpack (0.1.1)
     pry (0.11.3)
       coderay (~> 1.1.0)
       method_source (~> 0.9.0)
     rainbow (3.0.0)
     rake (12.3.0)
-    rb-fsevent (0.10.2)
+    rb-fsevent (0.10.3)
     rb-inotify (0.9.10)
       ffi (>= 0.5.0, < 2)
     rspec (3.7.0)
@@ -113,9 +115,9 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.7.0)
     rspec-support (3.7.1)
-    rubocop (0.52.1)
+    rubocop (0.53.0)
       parallel (~> 1.10)
-      parser (>= 2.4.0.2, < 3.0)
+      parser (>= 2.5)
       powerpack (~> 0.1)
       rainbow (>= 2.2.2, < 4.0)
       ruby-progressbar (~> 1.7)

data/README.adoc

@@ -98,13 +98,17 @@ The document model ("IsoDoc") used in document generation
 intends to introduce rigour into the ISO
 standards authoring process; the existing 
 https://www.iso.org/iso-templates.html[Microsoft Word template from ISO]
-do not support such rigour down to the element level.
+do not support such rigour down to the element level. It also introduces
+flexibility by decoupling the document structure from its presentation.
 
 The ISO International Standard format is prescribed in
 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"],
 to a level amenable to an explicit document model. A formal document
 model would allow checking for consistency in format and content, and expedite
-authoring and quality control of ISO standards. Authoring standards through a more abstract formal model also permit enhanced functionality such as cross reference link checking and auto numbering of sections, figures, tables and formulas.
+authoring and quality control of ISO standards. Authoring standards through a 
+more abstract formal model also permit enhanced functionality such as 
+cross-reference link checking and auto-numbering of sections, figures, tables and formulas.
+Outputting a document in different languages also becomes straightforward.
 
 The document model for ISO Standards specifically is derived from a more general
 https://github.com/riboseinc/isodoc-models[StandardDocument model]. Other
@@ -112,10 +116,7 @@ ISO-like standards can also be derived from this more general model;
 CSD (https://github.com/riboseinc/csd, https://github.com/riboseinc/asciidoctor-csd)
 is one such instance.
 
-The document model for ISO Standards is still under development, but it already contains
-all the markup needed to render the
-https://www.iso.org/publication/PUB100407.html["Rice document"], the ISO's
-model document of an international standard, and all the structures described
+The document model for ISO Standards contains all the structures described
 in ISO/IEC DIR 2. It is expressed as a
 link:lib/asciidoctor/iso/isostandard.rnc[Relax NG Compact schema]; actual
 validation occurs against its link:lib/asciidoctor/iso/isostandard.rng[full Relax
@@ -153,7 +154,31 @@ http://discuss.asciidoctor.org/footnotes-with-paragraph-breaks-td4130.html[by de
 XML to break up paragraphs within a footnote.)
 
 [[model_additions]]
-=== Asciidoctor 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 asciidoctor-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
 
@@ -176,7 +201,30 @@ domain:[rice]
 _paddy_ (<<paddy>>) from which the husk only has been removed
 --
 
-==== Paragraph alignment
+=== 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:
 
@@ -195,7 +243,7 @@ This paragraph is aligned center
 This paragraph is justified, which is the default
 --
 
-==== Reviewer notes
+=== 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. 
@@ -236,7 +284,7 @@ Profile?!
 ****
 --
 
-==== Strikethrough and Small Caps
+=== Strikethrough and Small Caps
 
 The following formatting macros are used for strikethrough and small caps text:
 
@@ -246,7 +294,7 @@ The following formatting macros are used for strikethrough and small caps text:
 [smallcap]#small caps text#
 --
 
-==== Count of table header and footer rows
+=== 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
@@ -266,7 +314,7 @@ stem:[w_max]
 |===
 --
 
-==== Inline clause numbers
+=== 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`:
@@ -280,7 +328,7 @@ attribute `inline-header`:
 consisting of a conical sample divider
 --
 
-==== Bibliographic details
+=== Bibliographic details
 
 Citations can include details of where in the document the citation is located; these
 are entered by suffixing the type of locality, followed by the reference. Multiple
@@ -297,7 +345,40 @@ example:
 The references cannot contain spaces. Any text following the sequence of localities
 will be displayed instead of the localities.
 
-==== Block Quotes
+=== Additional warning types
+
+Asciidoctor natively supports the ISO admonitions "Caution", "Warning", and "Important"
+through its admonition syntax:
+
+[source,asciidoctor]
+--
+CAUTION: This is a single-block caution
+
+[WARNING]
+====
+This is a
+
+multiple-block warning
+====
+--
+
+If the admonitions "Danger" and "Safety Precaution" are needed, they should be indicated
+through a `type` attribute, which will override the admonition type appearing in the Asciidoc:
+
+[source,asciidoctor]
+--
+[type=Danger]
+CAUTION: This is a single-block caution
+
+[WARNING,type=Safety Precaution]
+====
+This is a
+
+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, 
@@ -417,11 +498,24 @@ render them.
 The gem relies on Asciidoctor document attributes to provide necessary
 metadata about the document. These include:
 
+`:nodoc:`:: Do not generate Word and HTML output, only generate XML output.
+Can be used as a command-line option (like all other document attributes):
+`asciidoctor -a nodoc -b iso -r "asciidoctor-iso" a.adoc`
+
+`:novalid:`:: Suppress validation.
+
+`: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.)
+Use if you wish to output an ISO standard in a language other than those three.
+A sample YAML file for English, with "Foreword" replaced with "Frontispiece",
+is available at link:spec/examples/english.yaml[].
+
 `:docnumber:`:: The ISO document number (mandatory)
 
 `:tc-docnumber:`:: The document number assigned by the Technical committee
 
-`:partnumber:`:: The ISO document part number
+`:partnumber:`:: The ISO document part number. (This can be "part-subpart" if this is an IEC document.)
 
 `:edition:`:: The document edition
 
@@ -492,6 +586,9 @@ not supplied. Example values: `JWG`, `JAG`, `AG` (advisory group), `AHG`, `SWG`,
 
 `:language:` :: The language of the document (`en` or `fr`)  (mandatory)
 
+`:script:` :: The script of the document (defaults to `Latn`). Must be supplied as
+`Hans` for Simplified Chinese.
+
 `:publisher:`:: The standards agency publishing the standard; can be multiple
 (comma-delimited). Defaults to `ISO`.
 
@@ -542,4 +639,4 @@ model document of an international standard. This repository includes:
 * the link:spec/examples/rice.doc[Word .doc rendering of the Rice document].
 * the link:spec/examples/rice.html[HTML rendering of the Rice document].
 
-
+See also `link:spec/asciidoctor-iso[]` for individual features.

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/lib/asciidoctor/iso/base.rb

@@ -23,7 +23,7 @@ module Asciidoctor
       def skip(node, name = nil)
         name = name || node.node_name
         w = "converter missing for #{name} node in ISO backend"
-        warning(node, w, nil)
+        Utils::warning(node, w, nil)
         nil
       end
 
@@ -31,7 +31,7 @@ module Asciidoctor
         File.join(File.dirname(__FILE__), File.join("html", file))
       end
 
-      def doc_converter
+      def doc_converter(node)
         IsoDoc::Convert.new(
           htmlstylesheet: html_doc_path("htmlstyle.css"),
           wordstylesheet:  html_doc_path("wordstyle.css"),
@@ -41,41 +41,45 @@ module Asciidoctor
           wordcoverpage: html_doc_path("word_iso_titlepage.html"),
           htmlintropage: html_doc_path("html_iso_intro.html"),
           wordintropage: html_doc_path("word_iso_intro.html"),
+          i18nyaml: node.attr("i18nyaml"),
+          ulstyle: "l3",
+          olstyle: "l2",
         )
       end
 
-      def init
+      def init(node)
         @fn_number = 0
         @draft = false
         @refids = Set.new
         @anchors = {}
+        @draft = node.attributes.has_key?("draft")
+        @novalid = node.attr("novalid")
       end
 
       def document(node)
-        init
+        init(node)
         ret1 = makexml(node)
         ret = ret1.to_xml(indent: 2)
         filename = node.attr("docfile").gsub(/\.adoc/, ".xml").
-          gsub(%r{^.*/}, '')
-        File.open("#{filename}", "w") { |f| f.write(ret) }
-        doc_converter.convert filename
+          gsub(%r{^.*/}, "")
+        File.open(filename, "w") { |f| f.write(ret) }
+        doc_converter(node).convert filename unless node.attr("nodoc")
         ret
       end
 
       def makexml(node)
         result = ["<?xml version='1.0' encoding='UTF-8'?>\n<iso-standard>"]
-        @draft = node.attributes.has_key?("draft")
         result << noko { |ixml| front node, ixml }
         result << noko { |ixml| middle node, ixml }
         result << "</iso-standard>"
         result = textcleanup(result.flatten * "\n")
         ret1 = cleanup(Nokogiri::XML(result))
         ret1.root.add_namespace(nil, "http://riboseinc.com/isoxml")
-        validate(ret1)
+        validate(ret1) unless @novalid
         ret1
       end
 
-      def is_draft
+      def draft?
         @draft
       end
 
@@ -92,42 +96,41 @@ module Asciidoctor
         end
       end
 
+      def term_source_attr(seen_xref)
+        { bibitemid: seen_xref.children[0]["target"],
+          format: seen_xref.children[0]["format"],
+          type: "inline" }
+      end
+
       def add_term_source(xml_t, seen_xref, m)
-        attr = { bibitemid: seen_xref.children[0]["target"],
-                 format: seen_xref.children[0]["format"],
-                 type: "inline" }
-        xml_t.origin seen_xref.children[0].content, **attr_code(attr)
-        m[:section] && xml_t.isosection do |s|
-          s.reference m[:section].gsub(/ /, "")
-        end
-        m[:text] && xml_t.modification do |mod| 
-          mod.p { |p| p << m[:text].sub(/^\s+/, "")  }
+        xml_t.origin seen_xref.children[0].content,
+          **attr_code(term_source_attr(seen_xref))
+        m[:text] && xml_t.modification do |mod|
+          mod.p { |p| p << m[:text].sub(/^\s+/, "") }
         end
       end
 
       TERM_REFERENCE_RE_STR = <<~REGEXP.freeze
-             ^(?<xref><xref[^>]+>)
-               (,\s(?<section>[^, ]+))?
+        ^(?<xref><xref[^>]+>([^<]*</xref>)?)
                (,\s(?<text>.*))?
-             $
+        $
       REGEXP
       TERM_REFERENCE_RE =
         Regexp.new(TERM_REFERENCE_RE_STR.gsub(/\s/, "").gsub(/_/, "\\s"),
                    Regexp::IGNORECASE | Regexp::MULTILINE)
 
-
-      def extract_termsource_refs(text)
+      def extract_termsource_refs(text, node)
         matched = TERM_REFERENCE_RE.match text
         if matched.nil?
-          warning(node, "term reference not in expected format", text)
+          Utils::warning(node, "term reference not in expected format", text)
         end
         matched
       end
 
       def termsource(node)
-        matched = extract_termsource_refs(node.content) or return
+        matched = extract_termsource_refs(node.content, node) || return
         noko do |xml|
-          attrs = { status: matched[:text] ? "identical" : "modified" }
+          attrs = { status: matched[:text] ? "modified" : "identical" }
           xml.termsource **attrs do |xml_t|
             seen_xref = Nokogiri::XML.fragment(matched[:xref])
             add_term_source(xml_t, seen_xref, matched)
@@ -135,7 +138,6 @@ module Asciidoctor
           end
         end.join("\n")
       end
-
     end
   end
 end