Inline YAML proposal

[opoudjis]

@gbuehler @ghobona @ogcscotts : We discussed in our latest teleconference the complaint from editors that they have to edit lots of little separate requirement files for a Modspec document, instead of being able to edit a single document containing all the requirements at the same time.

The requirement to have the requirements in separate files for processing is legitimate, but there are a couple of little-used concepts in Metanorma, which we could combine to address this preference:

YAML can be incorporated in an Asciidoc document, as sourcecode. We are already using that, to add YAML-structured metadata into other Metanorma flavours, e.g. for document history.

In addition, there is functionality to associate a filename with sourcecode snippets: this was included to do exactly this, to export soucecode snippets to a filename. We've never actually done it.

I suggest that we:

• add Modspec requirements to a document
  • as YAML sourcecode,
  • with filename= telling it what file to export each YAML file to
  • and wrapped in a requirement block, so that Metanorma knows that the YAML is actually intended as a Modspec requirement
• add functionality to Metanorma generically, to export any sourcecode with a filename attribute to that filename
• add functionality to Metanorma, to process YAML embedded inside a Modspec requirement like a Modspec YAML file, and generate Metanorma rendering — as an extension of Integrate this with Metanorma via a new plugin modspec-ruby#2
  • I could process the extracted YAML files instead, but I'd say that's more complicated than the alternative, not less.

This is introducing another way of doing Modspec requirements out of YAML:

• The approach in https://www.metanorma.org/blog/2024-04-04-ogc-modspec-in-yaml/ takes external YAML files, and converts them, via yaml2text and a supplied Liquid template, to Metanorma Asciidoc markup of requirements as definition lists. That then gets parsed into Metanorma XML.
• The ticket Integrate this with Metanorma via a new plugin modspec-ruby#2 proposes to sidestep the Liquid template, and convert YAML files to Modspec ruby objects, and then export them back out as Asciidoc. Or XML. I don't know, I haven't gotten there yet. (But I would prefer Asciidoc, and to keep all input to Metanorma in the same format, than stitch XML together generated two different ways.)
• I'm now proposing to use that approach with YAML found inside of the file, instead of only processing standalone YAML.

So, to give an illustration:

= Titile
:mn-document-class: ogc

== Clause

[requirement]
====
[source,yaml,filename=req/1.yaml]
----
conformance_classes:
- name: Validation of XML instance for metadata basic information
  identifier: https://standards.isotc211.org/19115/-1/1/conf/metadata-xml/basic
  target: https://standards.isotc211.org/19115/-1/1/req/metadata-xml/basic
  dependencies:
  - https://standards.isotc211.org/19115/-1/1/conf/metadata-minimal-xml
  - https://standards.isotc211.org/19115/-1/1/conf/metadata-xml/common
  - https://standards.isotc211.org/19115/-1/1/conf/metadata-xml/multilingual
----
====

[requirement]
====
[source,yaml,filename=req/2.yaml]
----
identifier: /req/relief/classes
statement: "For each UML class defined or referenced in the Relief Package:"
parts:
- The Implementation Specification SHALL contain an element which represents the
same concept as that defined for the UML class.
- The Implementation Specification SHALL represent associations with the same
source, target, direction, roles, and multiplicities as those of the UML class.
----
====

Processing will do the following:

• Extract the contents of the first source snippet to the file req/1.yaml
• Extract the contents of the second source snippet to the file req/2.yaml
• Once Integrate this with Metanorma via a new plugin modspec-ruby#2 is implemented, you will be able to read a YAML file like req/1.yaml into a Metanorma document, as a Modspec requirement
• I'm proposing that Metanorma doesn't even need to do that: it sees YAML inside a requirement in markup, realises this is Modspec YAML, and uses the same method for inline YAML snippets as it will for Integrate this with Metanorma via a new plugin modspec-ruby#2 and external YAML files: it converts that inline YAML into a Modspec requirement, and renders it accordingly.
• And because we're extracting the contents already with the filename attribute, you get your standalone YAML files anyway if you want them. (If you don't want them, don't supply the filename attribute: the processing still happens.)

My assumption from what you've said tonight is that your editors would rather edit a single file containing two YAML snippets, like the above, than two separate YAML files like req/1.yaml and req/2.yaml

This is a small bit of work, and it's yet another way of doing things; but it builds on notions that are halfway there already in Metanorma.

Let me know if this kind of thing is of interest to your editors. I am going to implement metanorma/modspec-ruby#2 anyway; the code for that would end up reused for this.