You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@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
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
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.
The text was updated successfully, but these errors were encountered:
@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:
filename=
telling it what file to export each YAML file toThis is introducing another way of doing Modspec requirements out of YAML:
So, to give an illustration:
Processing will do the following:
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.
The text was updated successfully, but these errors were encountered: