Embed Metanorma for OSD support

[Sveino]

Is your feature request related to a problem? Please describe.
From 2025 shall Online Standards Development (OSD) be use for creating IEC standards. To support SchemaDev we would need to be able to support the IEC/ISO SMART work and integration with OSD.

Describe the solution you'd like
I would like that we utilize Metanorma library to generate the file format the is supported by OSD and any other standardisation organisation. Primarily would be the ability to generate from our internal AsciiDoc information, but importing could also be relevant.
It also looks like we can use the same library to generate Word document.

Describe alternatives you've considered
Alternative would be to look at other library or write the export separate.

Additional context
Here are relevant sources:

• OSD IT resources

• Metanorma | Standards beyond words

• metanorma/metanorma: The Metanorma project: www.metanorma.org

• Ruby gem to convert HTML and DOCX into AsciiDoc format.

• Writing in AsciiDoc, Part 4

• Metanorma now supports IEC standardization deliverables

[bartkl]

Hopefully this is not off-topic, otherwise just ignore and it'll come up some other time ;).

It would be great if we could reuse as much of the generated and manually written AsciiDoc fragments/documents as possible for outputting the multitude of deliverables.

I envision something like:

(Antora is just an example, although I hope to show you guys how cool it is pretty soon.)

So, I think it's wise not to overdo the automation, and just create a IEC spec by hand, but include/reuse as much sections from available AsciiDoc parts as possible. Same for the web documentation.

Just needed to share, haha.

Note

The above may seem straightforward, but I've seemed to notice Metanorma uses some custom macros, making those AsciiDocs not entirely suited for Antora. Likewise, Antora has some internal resource ID for targeting docs in xrefs. These are valid according to the standard, but won't be understood by anything else then Antora. Anyways, I'll spare you the details for now. I just think a workflow like that would be great.

[Sveino]

The goal is to have workflow that ensure that all artifacts are generated as part of a pull request to have clear input requirement and that create consistency, completeness and validation of the output artifacts before any merging.
There could be a set of intermedial steps, but the high-level diagram should show any external source is mapped into an internal AsciiDoc structure that can produce all relevant output artifacts. The core "master" will be a set of part document that is then combined to create a given output document. If Antora and Metanorma has different requirement to the source AsciiDoc structure the internal "master" must be the superset in regards to structure so that both source to Antora and Metanorma can be generated.
When I refer to Metanorma, I am not really referring to the user interface, but rather the underlying libraries that can generated the XSD. If the Metanorma does not comply with the "master" structure it will be considered an input to the "master" when an updated is created by Metanorma. it would be good if you can update the diagram to reflect this - to see if we have common understanding.

[bartkl]

The goal is to have workflow that ensure that all artifacts are generated as part of a pull request to have clear input requirement and that create consistency, completeness and validation of the output artifacts before any merging.

Agreed.

There could be a set of intermedial steps, but the high-level diagram should show any external source is mapped into an internal AsciiDoc structure that can produce all relevant output artifacts.

What external sources should I think of here?

The core "master" will be a set of part document that is then combined to create a given output document. If Antora and Metanorma has different requirement to the source AsciiDoc structure the internal "master" must be the superset in regards to structure so that both source to Antora and Metanorma can be generated.

Yes, exactly. These are the squares on the left in my diagram. And indeed, these should be flavour-free AsciiDoc to be used anywhere (or some trivial post-processing can be used at worst). These are included (where possible) or referred to when composing the IEC document and the plain documentation in my diagram (which is just an example to illustrate the point btw).

When I refer to Metanorma, I am not really referring to the user interface, but rather the underlying libraries that can generated the XSD.

The reference to Metanorma in my diagram points to the processor that renders output formats (PDF, etc.). I was not aware XSDs can be used to validate the structural conformity, that's nice :) (but outside of the scope of my simple diagram).

If the Metanorma does not comply with the "master" structure it will be considered an input to the "master" when an updated is created by Metanorma.

I'm not following. "The Metanorma" is our composed IEC document in this example? And "master" refers to the IEC template provided by Metanorma? So when their template is updated, and our document doesn't conform, our document "serves as input" for the new template? In what sense? (I could be completely misunderstanding here.)

it would be good if you can update the diagram to reflect this - to see if we have common understanding.

To be sure I'd like to emphasize: the diagram was kept intentionally simple to demonstrate merely the fact that it is desired to have reusable parts of AsciiDoc for use in several types of documents, which a variety of toolchains can use for rendering and validating andsoforth. I believe we are on the same page there at least, but I didn't understand everything you said.

---

We clearly want the same things but we're in the process of aligning our language I guess 😄.

[Sveino]

What external sources should I think of here?

If we are not tracking all the changes done though the voting process using OSD we would need to have the output XML from IEC as input to our next release. We should track that these are changes from IEC.
We can use other tools like ELOT or Word and PDF. We would also need to combine documentation with example that could be master in other tools.

The reference to Metanorma in my diagram points to the processor that renders output formats (PDF, etc.). I was not aware XSDs can be used to validate the structural conformity, that's nice :) (but outside of the scope of my simple diagram).

It should have been XML not XSD, but I believe there are validation done on the XML.

notice Metanorma uses some custom macros, making those AsciiDocs not entirely suited for Antora.

This was a bit of my concerns in regards to the diagram. But I think we have the same overall goad. We should probably address the concrete requirement to the AsciiDocs that is different between Metanoma and Antora. My point is that we need to have a super structure so that we do not need to add information that is specific for a tool.

[bartkl]

Ahh, yes, now I get it.

We should probably address the concrete requirement to the AsciiDocs that is different between Metanoma and Antora. My point is that we need to have a super structure so that we do not need to add information that is specific for a tool.

Precisely. This is what I tried to show in my diagram.

Anyway, sorry if this was not entirely on-topic. At least it's useful dialogue though 🙂.

[Sveino]

it was totally on topic.