metanorma / metanorma-generic

Metanorma for the (fictitious) Acme Corporation

metanorma-generic: Metanorma template gem for customisation

Formerly known as metanorma-acme

Functionality

This gem processes Metanorma documents with a configurable template for document options. It is intended for flavours of Metanorma that do not require extensive gem customisation: these flavours inherit from metanorma-generic, instead of directly from metanorma-standoc.

The gem currently inherits from the metanorma-standoc gem, and aligns closely to it.

Configuration

Gem can be configured in 2 ways: 1. By creating yaml config file with name metanorma.yml, see metanorma.yml.example for example. 2. By using the Metanorma::Generic.configuration method directly; for example

---
Metanorma::Generic.configure do |config|
  config.organization_name_short = 'My Organization'
  config.organization_name_long = 'My Organization name'
  config.document_namespace = 'https://open.ribose.com/standards/mine'
  config.xml_root_tag = 'mine-standard'
  config.logo_path = '/metanorma-mine/lib/isodoc/mine/html/logo.jpg'
  config.validate_rng_file = '/metanorma-mine/lib/metanorma/mine/mine.rng'
  config.htmlcoverpage = '/metanorma-mine/lib/isodoc/mine/html/html_mine_titlepage.html'
  config.htmlintropage = '/metanorma-mine/lib/isodoc/mine/html/html_mine_intro.html'
  config.htmlstylesheet = '/metanorma-mine/lib/isodoc/mine/html/htmlstyle.scss'
  config.scripts = '/metanorma-mine/lib/isodoc/mine/html/scripts.html'
  config.scripts_pdf = '/metanorma-mine/lib/isodoc/mine/html/scripts.prd.html'
  config.standardstylesheet = '/metanorma-mine/lib/isodoc/mine/html/'
  config.header = '/metanorma-mine/lib/isodoc/mine/html/header.html'
  config.wordcoverpage = '/metanorma-mine/lib/isodoc/mine/html/word_mine_titlepage.html'
  config.wordintropage = '/metanorma-mine/lib/isodoc/mine/html/word_mine_intro.html'
  config.wordstylesheet = '/metanorma-mine/lib/isodoc/mine/html/wordstyle.scss'
end
---

More information about how to configure this gem is given in Simple adoption on the metanorma.com site.

metanorma-generic's Issues

Allow customisation of Web fonts

Allow customization of `doctype` and `docstatus`

There are 4 main reasons why people want a custom flavor:

1. Presentation
2. Document type
3. Document status
4. Document identifier

We need to deal with 2 and 3 via YAML.

Method to customize document identifiers

Users who use this gem will want to customize their document identifiers. Let's use the ISO document identifier scheme as an example to adapt for.

The ISO document identifier scheme differs by stage:

Template for unpublished:

• ISO {stage} {report number}[-{part number}]:{year}

Template for published:

• ISO {stage} {report number}[-{part number}]:{year}

Examples:

• ISO CD XXXX–2 (“Committee Draft of ISO XXXX Part 2”);
• ISO YYYY-3:2020 (“ISO YYYY Part 3, 2020 edition”).

Template for unpublished amendments:

• ISO {stage} {report number}[-{part number}]:{year}/{“Cor”|“Amd”} {number}:{year}

For example:

• ISO/IEC 14888-2:2008/Cor 1:2015 (“First correction—issued in 2015—to ISO/IEC 14888 Part 2, 2008 edition”);
• ISO/IEC 18031:2011/Amd 1:2017 (“First amendment—issued in 2017—to ISO/IEC 18031, 2011 edition”)

We can use a YAML structure to express this.

If it is simple:

docid_scheme: "{orgid} {docnumber}"

If more complex:

docid_scheme:
  - doctype: [ standard, technical-report ]
    stages:
       published: "ISO {report number}[-{part number}]:{year}"
       working-draft: "ISO {stage} {report number}[-{part number}]:{year}"
       committee-draft: "ISO {stage} {report number}[-{part number}]:{year}"
    ...
  - doctype: [ amendment ]
    stages:
      published: "ISO {report number}[-{part number}]:{year}/{“Cor”|“Amd”} {number}:{year}"
      working-draft: "ISO {stage} {report number}[-{part number}]:{year}/{“Cor”|“Amd”} {number}:{year}"
      committee-draft: "ISO {stage} {report number}[-{part number}]:{year}/{“Cor”|“Amd”} {number}:{year}"
    ...

This ticket needs more discussion when it gets tackled. Ping me for details!

Metanorma simple adoption not working

Hello guys,

I have spent a lot of time for customizing via YAML the metanorma-generic flavor (because we don't want to program anything). The metanorma.yml seems not parsed and I can't find any further guidance in the documentation.

1. Our file report1/document.adoc includes :mn-document-class: generic
2. I added file report1/metanorma.yml with content from https://github.com/metanorma/metanorma-generic/blob/main/metanorma.yml.example and modified some fields (e.g., organization_name_long)
3. I built the doc with latest docker image (tried with metanorma site and metanorma compile).
   Example: docker run -v "d:\mydir":/metanorma metanorma/mn metanorma site generate --agree-to-terms

The metanorma.yml file (not the collection configuration, but the one in the report) is ignored. The documentation does not clarify the second approach with "Metanorma::Generic.configuration method" (where should be provided this config ?).

Could you please provide some tips for solving this problem ?

Thank you very much.

Identifier template

Create a config parameter that is a Liquid template for document identifiers, drawing on metadata fields. I'm not in love with the idea, but I think it's the only way to keep RSD without any code, and it would end up becoming a separate ticket for me.

For that scheme to work, we would need to add the config values into the hash of metadata values that go into liquid, and expand it. So the default identifier format would end up as {{ org_abbrev}} {{ docnum }}, and the current RSD identifier would be {{ docnum }} {{ status_abbrev }}.

Implement NIST CAXIF as skin of generic

Note: not as a new gem inheriting from generic, but as a pure skin of generic—bundling generic with stylesheets and config. If we can't do that, and require gems for each new deployment of an SDO, we will never get scale.

That means they don't get to have a wishlist: it is a bare bones implementation, as much as can be put in by configuration.

"NIST CAXIF: want a new flavour, to publish EXPRESS docs and non-MDA docs"

This hopefully does not make the skin implementation impossible.

Metanorma-Acme is now Metanorma-Generic

Shall the rename exercise commence...

Refactor HTML CSS

metanorma/isodoc#112

Add document attribute to point to `metanorma.yml`

A user may have multiple metanorma.yml files or a single one located outside the current directory.

The goal is to allow the user to do:

= My title
:customize: /Users/me/mn/organization-1.yml
..

And Metanorma Acme will ignore the local metanorma.yml.

There is currently no mn-samples-generic repository

https://github.com/metanorma/metanorma-generic/actions/runs/4654810188/jobs/8236867757

Needs appveyor integration

Rename gem to metanorma-generic

Will follow the checklist in metanorma/metanorma#90