metanorma-generic 2.7.0 → 2.7.2

data/lib/metanorma/generic/processor.rb

@@ -15,10 +15,7 @@ module Metanorma
       end
 
       def output_formats
-        super.merge(
-          html: "html",
-          doc: "doc",
-        )
+        configuration.formats
       end
 
       def fonts_manifest

data/lib/metanorma/generic/reqt.rng

@@ -1,20 +1,27 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<grammar xmlns="http://relaxng.org/ns/structure/1.0" datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes">
+<grammar xmlns:a="http://relaxng.org/ns/compatibility/annotations/1.0" xmlns="http://relaxng.org/ns/structure/1.0" datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes">
   <!--
     Presupposes isodoc.rnc, is included in it
     include "isodoc.rnc" { }
+    
+    This is the Metanorma default provisions model; it is overridden by other provisions models,
+    such as Modspec
   -->
   <define name="requirement">
+    <a:documentation>Specification of an attribute of a subject that is required.
+NOTE: A requirement can contain other requirements</a:documentation>
     <element name="requirement">
       <ref name="RequirementType"/>
     </element>
   </define>
   <define name="recommendation">
+    <a:documentation>Specification of an attribute of a subject that is recommended</a:documentation>
     <element name="recommendation">
       <ref name="RequirementType"/>
     </element>
   </define>
   <define name="permission">
+    <a:documentation>Specification of an attribute of a subject that is permitted</a:documentation>
     <element name="permission">
       <ref name="RequirementType"/>
     </element>
@@ -22,80 +29,101 @@
   <define name="RequirementType">
     <optional>
       <attribute name="obligation">
-        <ref name="ObligationType"/>
-      </attribute>
-    </optional>
-    <optional>
-      <attribute name="unnumbered">
-        <data type="boolean"/>
-      </attribute>
-    </optional>
-    <optional>
-      <attribute name="number"/>
-    </optional>
-    <optional>
-      <attribute name="subsequence"/>
-    </optional>
-    <optional>
-      <attribute name="keep-with-next">
-        <data type="boolean"/>
-      </attribute>
-    </optional>
-    <optional>
-      <attribute name="keep-lines-together">
-        <data type="boolean"/>
+        <a:documentation>An attribute that may be used to override the obligation represented in
+the tag name of the top level containers</a:documentation>
+        <ref name="ReqtObligationType"/>
       </attribute>
     </optional>
     <attribute name="id">
       <data type="ID"/>
     </attribute>
+    <ref name="NumberingAttributes"/>
+    <ref name="BlockAttributes"/>
     <optional>
-      <attribute name="filename"/>
-    </optional>
-    <optional>
-      <attribute name="model"/>
+      <attribute name="filename">
+        <a:documentation>File name of the requirement model when exported</a:documentation>
+      </attribute>
     </optional>
     <optional>
-      <attribute name="type"/>
+      <attribute name="model">
+        <a:documentation>Model of requirements realised by this requirement, e.g. "ogc" for Modspec</a:documentation>
+      </attribute>
     </optional>
     <optional>
-      <attribute name="tag"/>
+      <attribute name="type">
+        <a:documentation>Type of requirement; does not override labelling, unlike `class`</a:documentation>
+      </attribute>
     </optional>
     <optional>
-      <attribute name="multilingual-rendering">
-        <ref name="MultilingualRenderingType"/>
+      <attribute name="class">
+        <a:documentation>Class of provision, used to sequence and label that class separately.
+By default, provisions are sequenced and labelled as requirements, recommendations, or
+permissions, by obligation; the class overrides that</a:documentation>
       </attribute>
     </optional>
     <optional>
-      <ref name="reqtitle"/>
+      <ref name="reqtitle">
+        <a:documentation>Human-readable title of the requirement</a:documentation>
+      </ref>
     </optional>
     <optional>
-      <ref name="label"/>
+      <ref name="reqtlabel">
+        <a:documentation>Formal identifier with which the requirement is referenced</a:documentation>
+      </ref>
     </optional>
     <zeroOrMore>
-      <ref name="subject"/>
+      <ref name="subject">
+        <a:documentation>The party subject to the obligation stated in the requirement</a:documentation>
+      </ref>
     </zeroOrMore>
     <zeroOrMore>
-      <ref name="reqinherit"/>
+      <ref name="reqinherit">
+        <a:documentation>Reference to the identifier of another requirement, of which this requirement
+is a subclass, and from which it inherits attributes</a:documentation>
+      </ref>
     </zeroOrMore>
     <zeroOrMore>
-      <ref name="classification"/>
+      <ref name="classification">
+        <a:documentation>Key/Value pairs of metadata used to describe the requirement.
+A key can be associated with multiple values</a:documentation>
+      </ref>
     </zeroOrMore>
     <zeroOrMore>
       <choice>
-        <ref name="measurementtarget"/>
-        <ref name="specification"/>
-        <ref name="verification"/>
-        <ref name="import"/>
-        <ref name="description"/>
-        <ref name="component"/>
+        <ref name="measurementtarget">
+          <a:documentation>Quantitative statement of metrics that the requirement realises</a:documentation>
+        </ref>
+        <ref name="specification">
+          <a:documentation>Formal specification of the requirement. Expected to be machine-readable</a:documentation>
+        </ref>
+        <ref name="verification">
+          <a:documentation>Processes or code used to verify that the requirement is being complied
+with. Can be a test (including test code), or a compliance statement</a:documentation>
+        </ref>
+        <ref name="import">
+          <a:documentation>A reference to source code or a statement of prerequisites which is defined elsewhere</a:documentation>
+        </ref>
+        <ref name="description">
+          <a:documentation>Descriptive statement of the content of the requirement. Is expected to
+be human-readable, and to contain formatting markup following Metanorma
+conventions. Is expected to be discursive, and be resumed after
+interruption by other sub-containers</a:documentation>
+        </ref>
+        <ref name="component">
+          <a:documentation>Provisions nested within this provision, which cannot be referenced autonomously and have
+subclasses specific to the parent provision. Not expressed with provision metadata</a:documentation>
+        </ref>
       </choice>
     </zeroOrMore>
     <optional>
-      <ref name="reqt_references"/>
+      <ref name="reqt_references">
+        <a:documentation>A list of references for the requirement, following the Relaton model</a:documentation>
+      </ref>
     </optional>
     <zeroOrMore>
       <choice>
+        <a:documentation>Provisions nested within this provision, which are self-standing and do not have
+subclasses specific to the parent provision</a:documentation>
         <ref name="requirement"/>
         <ref name="recommendation"/>
         <ref name="permission"/>
@@ -104,10 +132,10 @@
   </define>
   <define name="reqtitle">
     <element name="title">
-      <ref name="FormattedString"/>
+      <ref name="LocalizedMarkedUpString"/>
     </element>
   </define>
-  <define name="label">
+  <define name="reqtlabel">
     <element name="identifier">
       <oneOrMore>
         <ref name="TextElement"/>
@@ -155,7 +183,9 @@
   </define>
   <define name="component">
     <element name="component">
-      <attribute name="class"/>
+      <attribute name="class">
+        <a:documentation>Class of component</a:documentation>
+      </attribute>
       <ref name="RequirementSubpart"/>
     </element>
   </define>
@@ -167,44 +197,36 @@
     </element>
   </define>
   <define name="RequirementSubpart">
-    <optional>
-      <attribute name="type"/>
-    </optional>
-    <optional>
-      <attribute name="exclude">
-        <data type="boolean"/>
+    <a:documentation>A subcontainer can be either machine-readable or human-readable, or a
+mixture of the two.
+A machine-readable component can be included as source code with
+nomination of the language</a:documentation>
+    <optional>
+      <attribute name="type">
+        <a:documentation>Type of sub-container.
+For example a `verification[@type = "unit-test"]` contains a unit test of a single
+feature, and is to be treated differently from
+`verification[@type = "comprehensive"]`, which represents a comprehensive test suite</a:documentation>
       </attribute>
     </optional>
     <optional>
-      <attribute name="keep-with-next">
-        <data type="boolean"/>
-      </attribute>
-    </optional>
-    <optional>
-      <attribute name="keep-lines-together">
+      <attribute name="exclude">
+        <a:documentation>Indicates that the current sub-container is only intended to be
+machine-readable, and is not to be rendered as document output</a:documentation>
         <data type="boolean"/>
       </attribute>
     </optional>
-    <optional>
-      <attribute name="tag"/>
-    </optional>
-    <optional>
-      <attribute name="multilingual-rendering">
-        <ref name="MultilingualRenderingType"/>
-      </attribute>
-    </optional>
+    <ref name="BlockAttributes"/>
     <oneOrMore>
       <choice>
+        <a:documentation>Content of subpart: blocks, rather than provisions</a:documentation>
         <ref name="BasicBlock"/>
         <ref name="component"/>
       </choice>
     </oneOrMore>
   </define>
-  <define name="ObligationType">
-    <choice>
-      <value>requirement</value>
-      <value>recommendation</value>
-      <value>permission</value>
-    </choice>
+  <define name="ReqtObligationType">
+    <a:documentation>Values are "requirement", "recommendation", "permission"; multiple values can be comma-delimited</a:documentation>
+    <text/>
   </define>
 </grammar>

data/lib/metanorma/generic/version.rb

@@ -1,5 +1,5 @@
 module Metanorma
   module Generic
-    VERSION = "2.7.0".freeze
+    VERSION = "2.7.2".freeze
   end
 end

data/lib/metanorma/generic.rb

@@ -10,6 +10,10 @@ module Metanorma
     DOCUMENT_NAMESPACE = "https://www.metanorma.org/ns/generic"
     YAML_CONFIG_FILE = "metanorma.yml"
 
+    class DummyProcessor < ::Metanorma::Processor
+      def initialize; end # rubocop:disable Lint/MissingSuper
+    end
+
     class Configuration
       CONFIG_ATTRS = %i[
         organization_name_short
@@ -62,6 +66,7 @@ module Metanorma
         word_footnotefontsize
         xml_root_tag
         pdf_stylesheet
+        formats
       ].freeze
 
       def filepath_attrs
@@ -86,11 +91,31 @@ module Metanorma
         # Try to set config values from yaml file in current directory
         @yaml = File.join(File.dirname(self.class::_file || __FILE__), "..",
                           "..", YAML_CONFIG_FILE)
-        set_default_values_from_yaml_file(@yaml) if File.file?(@yaml)
+        set_default_values_from_yaml_file(@yaml)
+      end
+
+      # may be invoked multiple times, needs to not overwrite
+      def postprocess_defaults
+        default_org
+        default_formats
+        default_titles
+      end
+
+      def default_org
         self.organization_name_short ||= ORGANIZATION_NAME_SHORT
         self.organization_name_long ||= ORGANIZATION_NAME_LONG
         self.document_namespace ||= DOCUMENT_NAMESPACE
-        default_titles
+      end
+
+      # convert array to hash; if already is hash (no override in customize),
+      # don't reconvert
+      def default_formats
+        formats.is_a?(Hash) and return
+        self.formats ||= %w(html doc)
+        self.formats = self.formats.each_with_object({}) do |k, m|
+          m[k.to_sym] = k
+        end
+        self.formats.merge! DummyProcessor.new.output_formats
       end
 
       def default_titles
@@ -107,18 +132,25 @@ module Metanorma
       end
 
       def set_default_values_from_yaml_file(config_file)
-        root_path, default_config_options =
-          set_default_values_from_yaml_file_prep(config_file)
-        CONFIG_ATTRS.each do |attr_name|
-          value = default_config_options[attr_name.to_s]
-          value && filepath_attrs.include?(attr_name) and
-            value = absolute_path(value, root_path)
-          instance_variable_set("@#{attr_name}", value)
+        if File.file?(config_file)
+          root_path, default_config_options =
+            set_default_values_from_yaml_file_prep(config_file)
+          CONFIG_ATTRS.each do |attr|
+            set_default_value_from_yaml_file(attr, root_path,
+                                             default_config_options)
+          end
         end
+        postprocess_defaults
+      end
+
+      def set_default_value_from_yaml_file(attr, root_path, default_options)
+        value = default_options[attr.to_s]
+        value && filepath_attrs.include?(attr) and
+          value = absolute_path(value, root_path)
+        instance_variable_set("@#{attr}", value)
       end
 
       def set_default_values_from_yaml_file_prep(config_file)
-        # root_path = File.dirname(self.class::_file || __FILE__)
         root_path = File.dirname(config_file)
         default_config_options =
           YAML.safe_load(File.read(config_file, encoding: "UTF-8"))
@@ -135,11 +167,14 @@ module Metanorma
       end
 
       def absolute_path(value, root_path)
-        if value.is_a? Hash then absolute_path1(value, root_path)
-        elsif value.is_a? Array then absolute_path1_array(value, root_path)
-        elsif value.is_a?(String) && !value.empty? &&
-            !Pathname.new(value).absolute?
-          Pathname.new(File.join(root_path, value)).cleanpath.to_s
+        case value
+        when Hash then absolute_path1(value, root_path)
+        when Array then absolute_path1_array(value, root_path)
+        when String
+          if !value.empty? && !Pathname.new(value).absolute?
+            Pathname.new(File.join(root_path, value)).cleanpath.to_s
+          else value
+          end
         else value
         end
       end

data/metanorma-generic.gemspec

@@ -27,7 +27,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
   spec.required_ruby_version = Gem::Requirement.new(">= 3.1.0")
 
-  spec.add_dependency "metanorma-standoc", "~> 2.9.3"
+  spec.add_dependency "metanorma-standoc", "~> 2.10.0"
 
   spec.add_development_dependency "debug"
   spec.add_development_dependency "equivalent-xml", "~> 0.6"

data/metanorma.yml.example

@@ -8,6 +8,10 @@ logo_paths:
   - /metanorma-mine/lib/isodoc/mine/html/logo1.jpg
   - /metanorma-mine/lib/isodoc/mine/html/logo2.jpg
 validate_rng_file: /metanorma-mine/lib/metanorma/mine/mine.rng
+formats:
+  - html
+  - pdf
+  - doc
 htmlcoverpage: /metanorma-mine/lib/isodoc/mine/html/html_mine_titlepage.html
 htmlintropage: /metanorma-mine/lib/isodoc/mine/html/html_mine_intro.html
 htmlstylesheet: /metanorma-mine/lib/isodoc/mine/html/htmlstyle.scss
@@ -74,5 +78,5 @@ normref_titles:
 bibliography_titles:
   - Bibliography
 fonts_manifest:
-  - Font1
-  - Font2
+  Font1:
+  Font2:

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: metanorma-generic
 version: !ruby/object:Gem::Version
-  version: 2.7.0
+  version: 2.7.2
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-08-19 00:00:00.000000000 Z
+date: 2024-11-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: metanorma-standoc
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.9.3
+        version: 2.10.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.9.3
+        version: 2.10.0
 - !ruby/object:Gem::Dependency
   name: debug
   requirement: !ruby/object:Gem::Requirement