Write up Ribose-side workflow end to end for generating stepmod deliverables

[opoudjis]

There has been lots of time wasted because none of the Ribose developers have a clear overview of what the process is for generating stepmod deliverables, and who is responsible for making what happen. The process string up several repositories together, and any one of the developers is only seeing a small bit of the workflow.

The process needs to be written up, end to end. The fact that it is spread out among multiple repositories is already a vulnerability, and the fact that the process does not seem written down is even more of one.

[opoudjis]

I am going to start on this to shame @ronaldtse into actually doing this. No, it is not my goddamn job to do this.

[opoudjis]

https://github.com/metanorma/stepmod2mn/wiki/Workflow-to-transform-Express-into-Metanorma

@Intelligent2013 @HassanAkbar You need to elaborate on the bits of this that you are responsible for.

@ronaldtse You need to correct or expand on this.

@TRThurman once that is done, you need to be satisfied that you and your developers can make sense of this.

[TRThurman]

@opoudjis, What is Metanorma semantic XML?
Is the binding to html formally documented?
I also don't have permissions to edit the wiki. I am not sure I want to get in the middle of this....

[opoudjis]

@opoudjis, What is Metanorma semantic XML?

https://www.metanorma.org/author/approach/
https://www.metanorma.org/specs/metanorma-model-standoc/
https://github.com/metanorma/metanorma-model-iso/tree/main/grammars

Is the binding to html formally documented?

No, and I do not believe it would be a good use of our time to do so. The HTML, DOC, and PDF outputs are generated via an intermediate Presentation XML, which is not well-documented, and we are scrambling too hard to keep up to document it. I know I am. And in the future, the mappings to HTML are apparently going to become customisable, to deal with your requirements. In any case, the mapping of Metanorma Semantic XML to HTML is trivial at the sub-paragraph level (pretty much the same), and transparent at the super-paragraph level (clauses are divs, clause titles are headings); blocks are almost always divs.

I also don't have permissions to edit the wiki. I am not sure I want to get in the middle of this....

The problem I have is that nobody seems to want to get in the middle of this. But the documentation needs to be written.I can't do this alone, given that I only see the final 20% of the process.

Is your side of the document generation chain publicly documented, @TRThurman ? If so, where?

[TRThurman]

@opoudjis
The STEPmod documentation generation requirements are included in
stepmod/help, which is available on the github site..
There is also a doc directory which has not been reviewed by myself. seems to be mostly just some early material...
Unfortunately there is not a formally documented requirements spec.
There is a good presentation by EuroStep in the help directory: xxx_tutorial_yyy.pdf

[HassanAkbar]

@Intelligent2013 @HassanAkbar You need to elaborate on the bits of this that you are responsible for.

@opoudjis This is a great initiative. I’ll start/collaborate on it right after finalizing some Glossarists tasks.

[TRThurman]

@HassanAkbar, progress to report?

[HassanAkbar]

@TRThurman I was busy with other tasks so I was unable to update this.
Will try to look into it later this week.