Creating your own Metanorma flavor

Customization via YAML

A simple Metanorma flavour can be created using Metanorma Generic's ability to use a metanorma-config.yml config file.

Place a metanorma-config.yml file in the same directory as your Metanorma AsciiDoc file, and populate it with any necessary attributes.

The following shows the default values that you can override, when necessary.

---
metanorma_name: generic
organization_name_short: Acme
organization_name_long: Acme Corp.
document_namespace: link:/standards/generic
xml_root_tag: 'generic-standard'
logo_path: lib/isodoc/generic/html/logo.jpg
logo_paths: []
validate_rng_file: lib/metanorma/generic/generic.rng
formats:
- html
- doc
- pdf
htmlcoverpage: lib/isodoc/generic/html/html_generic_titlepage.html
htmlintropage: lib/isodoc/generic/html/html_generic_intro.html
htmlstylesheet: lib/isodoc/generic/html/htmlstyle.css
scripts: lib/isodoc/generic/html/scripts.html
standardstylesheet: lib/isodoc/generic/html/generic.css
header: lib/isodoc/generic/html/header.html
wordcoverpage: lib/isodoc/generic/html/word_generic_titlepage.html
wordintropage: lib/isodoc/generic/html/word_generic_intro.html
wordstylesheet: lib/isodoc/generic/html/wordstyle.css
i18nyaml: lib/isodoc/generic/html/i18n-en.yml
boilerplate: lib/metanorma/generic/boilerplate.xml
docid_template: "{{ organization_name_short }} {{ docnumeric }}"
published_stages: ["published", "withdrawn"]
committees: []
committees: [committee]
relations: []
default_stage: "published"
metadata_extensions: []
stage_abbreviations: (initials of stage)
doctypes: []
default_doctype: "standard"
html_bodyfont: "Overpass",sans-serif
html_headerfont: "Overpass",sans-serif
html_monospacefont: "Space Mono",monospace
html_normalfontsize: "1.0em"
html_monospacefontsize: "0.8em"
html_smallerfontsize: "0.9em"
html_footnotefontsize: "0.8em"
word_bodyfont: "Arial",sans-serif
word_headerfont: "Arial",sans-serif
word_monospacefont: "Courier New",monospace
word_normalfontsize: "12.0pt"
word_monospacefontsize: "11.0pt"
word_smallerfontsize: "10.0pt"
word_footnotefontsize: "9.0pt"
termsdefs_titles:
  - Terms and definitions
  - Terms, definitions, symbols and abbreviated terms
  - Terms, definitions, symbols and abbreviations
  - Terms, definitions and symbols
  - Terms, definitions and abbreviations
  - Terms, definitions and abbreviated terms
symbols_titles:
  - Symbols and abbreviated terms
  - Symbols
  - Abbreviated terms
  - Abbreviations
normative_references_titles:
  - Normative references
bibliography_titles:
  - Bibliography
webfont:
  - https://fonts.googleapis.com/css?family=Source+Sans+Pro:300,300i,600,600i&display=swap
  - https://fonts.googleapis.com/css2?family=Source+Code+Pro:ital,wght@0,300;0,600;1,300;1,600&display=swap
fonts_manifest:
  Source Sans Pro: ["Regular", "Light"]
  Source Serif Pro:

Key:

metanorma_name

Short name of the Metanorma flavour, for use in invoking the gem as software metanorma-generic ≥ v1.4.8. For example, metanorma -t {short name} document.adoc or :mn-document-class: {short name}.

organizationnameshort, organizationnamelong

Name of your organization

document_namespace

attribute for creating Metanorma Standoc XML, will be used for as namespace name for XML tags generated

xmlroottag

attribute for creating Metanorma Standoc XML, will be used as tag name for root tag

logo_path

path to a single logo file, used for metanorma metadata. As with all file locations in the configuration, these are relative paths from the gem root

logo_paths

list of paths of multiple logo files, used for metanorma metadata, and treated as an array (e.g. {{ logo_paths[0] }}) metanorma-generic ≥ v1.4.8. For example,

  - lib/isodoc/generic/html/logo1.jpg
  - lib/isodoc/generic/html/logo2.jpg
  - lib/isodoc/generic/html/logo3.jpg

validaterngfile

validation file with rules used in your flavour, see `generic.rng` for example. This and all other file directory paths are relative to the gem root.

htmlcoverpage, htmlintropage, htmlstylesheet, scripts

paths used for styling HTML output files. Accepts a path to a CSS (.css) or SASS/SCSS (.sass, .scss) file.

Examples available at the `metanorma-generic` gem

See examples at the `metanorma-generic` gem.

Note

In order to use SASS/SCSS stylesheets (.sass, .scss), which can include variables like html_bodyfont and html_headerfont, require the sassc gem to compile such files into normal CSS (.css). You will need to add the line `gem "sassc“ to your Gemfile to achieve this.

Alternatively, you can provide a pure CSS (.css) stylesheet by resolving all variables inside a SASS/SCSS stylesheet. e.g. resolve all the $ variables by filling in CSS-compliant values.

wordcoverpage, wordintropage, wordstylesheet, header

paths used for styling word output files.

Examples available at the `metanorma-generic` gem

See examples at the `metanorma-generic` gem.

docid_template

template to generate a document identifier, using Liquid template language, and metadata values (see Default metadata values); the config file values can also be used in the Liquid template metanorma-generic ≥ v1.4.1. In addition, values from the bibdata metadata of the document are available directly to Liquid, via the bibdata object; e.g. {{ bibdata.ext.doctype.type }} is the doctype of the document metanorma-generic ≥ v3.0.5.

i18nyaml

YAML file to be used for internationalization and labels metanorma-generic ≥ v1.6.3.

The configuration may instead be a hash of language abbreviations to files metanorma-generic ≥ v1.6.4.

Setting `i18nyaml` to point to language files

  en: yaml-en.yml
  fr: yaml-fr.yml

boilerplate

Predefined text file for inclusion in Metanorma XML metanorma-generic ≥ v1.6.4. The configuration may be a single file, or a hash of language abbreviations to files, as with i18nyaml. For the format of boilerplate files, see Predefined text.

published_stages

list of stages considered published

committee_types

list of possible hierarchical level of committees metanorma-generic ≥ v3.1.3. Assumes a single hierarchy. Note that the values here need to match the corresponding document attributes; e.g. a value of workgroup will correspond to the document attributes :workgroup:, :workgroup-number:, :workgroup-type:, :workgroup_2:, :workgroup-number_2:, :workgroup-type_2:, etc.

committees

list of legal committee values metanorma-generic ≥ v1.6.4. Assumes one level of committee.

relations

list of recognised relations to other documents, expressed through document attributes metanorma-generic ≥ v1.6.4

stage_abbreviations

hash of stages and their corresponding abbreviations. If not supplied, the initials of the stage are used, as is the default for Metanorma. This structure is used to configure stages.

doctypes

array or hash of legal document types metanorma-generic ≥ v1.4.8. If it is an array, only the document types are given; if it is a hash metanorma-generic ≥ v1.7.3, the document types are mapped to abbreviations.

Defining doctypes in an array

doctypes:
  - standard
  - guide

Defining doctypes in a hash

doctypes:
  standard:
  guide: G

default_doctype

default doctype metanorma-generic ≥ v1.4.8. If not supplied, the first element of doctypes is used; if that is not supplied either, standard is used.

formats

output formats supported metanorma-generic ≥ v2.7.1, specified as an array. If not supplied, the default is ["html", "doc"]. Every format specified needs to be supported with stylesheets and font settings appropriate for the format, as specified below.

html_bodyfont

The default font to use in HTML output for body text metanorma-generic ≥ v1.4.4.

html_headerfont

The default font to use in HTML output for headers metanorma-generic ≥ v1.4.4.

html_monospacefont

The default font to use in HTML output for monospace text metanorma-generic ≥ v1.4.4.

html_normalfontsize

The font size to use in HTML output for body text metanorma-generic ≥ v1.8.0.

html_monospacefontsize

The font size to use in HTML output for monospace text metanorma-generic ≥ v1.8.0.

html_smallerfontsize

The font size to use in HTML output for smaller than body text metanorma-generic ≥ v1.8.0.

html_footnotefontsize

The font size to use in HTML output for footnotes metanorma-generic ≥ v1.8.0.

word_bodyfont

The default font to use in DOC output for body text metanorma-generic ≥ v1.4.4.

word_headerfont

The default font to use in DOC output for headers metanorma-generic ≥ v1.4.4.

word_monospacefont

The default font to use in DOC output for monospace text metanorma-generic ≥ v1.4.4.

word_normalfontsize

The font size to use in DOC output for body text metanorma-generic ≥ v1.8.0.

word_monospacefontsize

The font size to use in DOC output for monospace text metanorma-generic ≥ v1.8.0.

word_smallerfontsize

The font size to use in DOC output for smaller than body text metanorma-generic ≥ v1.8.0.

word_footnotefontsize

The font size to use in DOC output for footnotes metanorma-generic ≥ v1.8.0.

metadata_extensions

A set of fields to be added to bibdata/ext for the document, as metadata. These can be entered in one of two formats:

General

Metanorma Generic also supports configuration via Ruby code. By following the steps below you can create your own Ruby Gem for your Metanorma flavour.

bundle init

Metanorma::Generic.configure do |config|
  config.organization_name_long = 'Ribose Inc.'
  config.organization_name_short = 'Ribose'
  config.document_namespace = 'https://open.ribose.com/standards/ribose'
  isodoc_rsd_html_folder = File.join(
    File.expand_path('isodoc', __dir__), 'ribose', 'html'
  )
  config.wordstylesheet = File.join(
    isodoc_rsd_html_folder, 'wordstyle.css'
  )
  config.standardstylesheet = File.join(isodoc_rsd_html_folder, 'ribose.css')
  config.header = File.join(isodoc_rsd_html_folder, 'header.html')
  config.wordcoverpage = File.join(
    isodoc_rsd_html_folder, 'word_rsd_titlepage.html'
  )
  config.wordintropage = File.join(isodoc_rsd_html_folder,
                                   'word_rsd_intro.html')
  config.htmlstylesheet = File.join(isodoc_rsd_html_folder,
                                    'htmlstyle.css')
  config.htmlcoverpage = File.join(isodoc_rsd_html_folder,
                                   'html_rsd_titlepage.html')
  config.htmlintropage = File.join(isodoc_rsd_html_folder,
                                   'html_rsd_intro.html')
  config.scripts = File.join(isodoc_rsd_html_folder, 'scripts.html')
  config.logo_path = File.join(isodoc_rsd_html_folder, 'logo.png')
  config.xml_root_tag = 'ribose-standard'
  rsd_rng_folder = File.join(File.expand_path('metanorma', __dir__), 'ribose')
  config.validate_rng_file = File.join(rsd_rng_folder, 'ribose.rng')
end
require 'metanorma/ribose'
require 'isodoc/generic'

require "metanorma"
require "metanorma/ribose/processor"
require "metanorma/ribose/converter"
module Metanorma
  module Rsd
  end
end
# This line registers your Metanorma Processor to the Metanorma Registry
Metanorma::Registry.instance.register(Metanorma::Rsd::Processor)

require "isodoc"
module IsoDoc
  module Rsd
    class Metadata < IsoDoc::Generic::Metadata
      def configuration
        Metanorma::Rsd.configuration
      end
    end
  end
end

require "isodoc"
require "isodoc/generic/html_convert"
require "isodoc/ribose/metadata"
module IsoDoc
  module Rsd
    class HtmlConvert < IsoDoc::Generic::HtmlConvert
      def configuration
        Metanorma::Rsd.configuration
      end
      def metadata_init(lang, script, labels)
        @meta = Metadata.new(lang, script, labels)
      end
    end
  end
end

require "metanorma/processor"
module Metanorma
  module Rsd
    class Processor < Metanorma::Processor
      def initialize
        @short = :ribose
        @input_format = :asciidoc
        @asciidoctor_backend = :ribose
      end
      def output_formats
        super.merge(
          html: "html",
          doc: "doc",
          pdf: "pdf"
        )
      end
      def version
        "Metanorma::Rsd #{Metanorma::Rsd::VERSION}"
      end
      def input_to_isodoc(file, filename)
        Metanorma::Input::Asciidoc.new.process(file, filename, @asciidoctor_backend)
      end
      def output(isodoc_node, outname, format, options={})
        case format
        when :html
          IsoDoc::Rsd::HtmlConvert.new(options).convert(outname, isodoc_node)
        when :doc
          IsoDoc::Rsd::WordConvert.new(options).convert(outname, isodoc_node)
        when :pdf
          IsoDoc::Rsd::PdfConvert.new(options).convert(outname, isodoc_node)
        else
          super
        end
      end
    end
  end
end

require "metanorma/ribose"
module Metanorma
  module Rsd
    VERSION = "0.0.1".freeze
  end
end

require "metanorma/standoc/converter"
require 'metanorma/generic/converter'
module Metanorma
  module Rsd
    # A {Converter} implementation that generates Ribose output, and a document
    # schema encapsulation of the document for validation
    #
    class Converter < Metanorma::Generic::Converter
      register_for "ribose"
    end
  end
end