Build fetched specification docsets using Metanorma flow

[strogonoff]

By invoking Metanorma gem function or executable, we want to build source specs, and down the line let the Jekyll theme show spec contents on open project sites.

[strogonoff]

Asked about the best way to build Metanorma input from Ruby in metanorma/metanorma#25. If no success, we can still call the executable according to its docs.

[strogonoff]

Proposed implementation route:

When the helpers plugin, after collecting specifications, encounters a spec with frontmatter which contains source_url, the helpers plugin would attempt to

1. fetch the source into a temporary directory,
2. execute Metanorma build function against the source to transform it into a set of HTML docs with the entry document index.html,
3. place the output in subdirectory _specs/[spec name]/,
4. if needed, remove the original spec file _specs/[spec name].adoc.

[ronaldtse]

Method to build in Ruby given in:
metanorma/metanorma#25 (comment)

[strogonoff]

Originally I thought we can create something like Metanorma-OPF, which can take input in any Metanorma flavour and produce consistent Open Project framework-compatible HTML output.

However, specs may not be all uniformly Metanorma projects: some are just PlantUML diagrams[0], for example. Basically we want to create a routine that can be called to build anything into [OP framework-compatible] HTML.

• I’m looking into requiring each spec that’s part of an Open Project site to have in its repo root a special dotfile referencing a Docker container, which OP build would pull and run against the source and get appropriately formatted HTML docs for inclusion into an OP site. E.g., we could have two containers: models[0] would reference a container calling PlantUML, and Metanorma specs[1] would reference a container with Metanorma binary and dependencies. Essentially it’s like a Makefile, but wrapping all system dependencies.

• Perhaps a better way to solve this could be by implementing multiple Jekyll plugins, each with its own system requirements, made configurable as to which plugin would be used to generate which spec (perhaps via spec frontmatter).

[0] https://github.com/riboseinc/metanorma-model-iso
[1] http://www.metanorma.com/specs/draft-ribose-asciirfc/

[ronaldtse]

@strogonoff it is indeed possible. Metanorma outputs a Metanorma XML file that can be transformed into HTML.

The basic gem that does this is called isodoc.

So we could either:

• subclass this gem, create one called isodoc-opf
• update this gem to produce OPF compliant html

Then things will work great.

[strogonoff]

@ronaldtse Sure. I think I’ve come up with a good enough way. (Roughly, each spec that’s part of project site can specify in its frontmatter, in addition to source URL, also a builder engine to be used against the source. Metanorma builders would use approach similar to metanorma/metanorma#25 (comment), PlantUML diagram builders would generate interlinked HTML files from files under /images/, in any case the output would be OP-compatible HTML.)