Update to the new Engineering Report template

[ghobona]

The OGC Technical Committee approved the new Engineering Report template on 20 June 2024.

https://github.com/opengeospatial/templates/issues/44#issuecomment-2185934733

Could you please update metanorma to generate the template when the document is an engineering report?

Please find the source files at https://portal.ogc.org/files/?artifact_id=109020

Please find the rendered document, https://portal.ogc.org/files/?artifact_id=109019

Please also note that some lines in the 00-executive_summary.adoc file have been commented out, for example [executive_summary]. Ideally, we would like to be able to use them and have metanorma handle them like it does with [.preface,type=executivesummary].

Cc: @ogcscotts @gbuehler

[ghobona]

@opoudjis Please also note that we would like Engineering Reports to have their bibliography appearing before the Annexes.

The source files linked to above actually have the bibliography appearing before the annexes but metanorma appears to be be set to always render the bibliography at the end of the document. 

[opoudjis]

The source files linked to above actually have the bibliography appearing before the annexes but metanorma appears to be be set to always render the bibliography at the end of the document.

Indeed it is. So @ghobona you want the bibliography before the annexes only for Engineering Reports, right?

[ghobona]

@opoudjis Yes, please. Only for Engineering Reports.

[opoudjis]

Metanorma is not dealing with an annex being unnumbered (and by appearing in front of the annexes, we're iterating the bibliography together with the annexes, but leaving it unnumbered. Fixing.

[opoudjis]

Please also note that some lines in the 00-executive_summary.adoc file have been commented out, for example [executive_summary]. Ideally, we would like to be able to use them and have metanorma handle them like it does with [.preface,type=executivesummary].

I'm not happy about doing so, because this is complicating the code for cosmetic reasons (including the detection of where the preface ends); but this is doable.

The additional types you are requesting are:

• [executive_summary]
• [overview]
• [future_outlook]
• [value_proposition]
• [contributors]

Be aware that these are going to be hardcoded categories. Any attempt to make these open-ended will be referred back to [.preface,type="..."] which actually is open-ended. (Which is why I am not happy about this.)

@ronaldtse Do not even THINK of asking me to generalise this across Metanorma.

[ghobona]

@opoudjis It would be acceptable to use [.preface,type=executivesummary].

Would [.preface,type=overview] have any effect?

[opoudjis]

Would [.preface,type=overview] have any effect?

The type in practice would make no difference, the .preface is doing the work. That said, I have started implementing the alternatives. But like I said, they do have to be a fixed list, since they are going to be hardcoded to be recognised as prefatory content.

[ghobona]

Ok, thanks.

[opoudjis]

I see you've also added the style attributes [introduction], [aims], [objectives] to the introduction. I'm going to hold off on using them for now.

[opoudjis]

Further questions:

• Do you want me to validate the Topics, the Introduction, the Outlook, and the Security, Privacy and Ethical Considerations clauses as present in Metanorma?
• Can I confirm that you no longer want a revision history?
• Right now, the bibliography appears as in Metanorma, as an unnumbered clause before the annexes. You have titled the bibliography as Annex A. Do you want it to be treated as an annex? The current markup,

[appendix,obligation=informative]
[[annex-bibliography]]
[bibliography]

will not work -- Asciidoctor does not let a clause be both an appendix and a bibliography; instead, I would need to apply a workaround I've already had to do for NIST, of an Appendix containing only a bibliography subclause, and not labelling that bibliography subclause separately. (That's already general to Metanorma, so no added implementation needed.)

[ghobona]

@opoudjis Apologies, I had not spotted the additional tags [introduction], [aims], [objectives] etc. If it is possible to support those, then please do.

Regarding validation, as this is for engineering reports, please follow the same approach as for this commit https://github.com/metanorma/metanorma-ogc/issues/527#issuecomment-1540010203 .

[opoudjis]

I'll support them all, then, but they won't do much. They are there in case you come to need semantic validation, but they are all going to be treated as equivalent to [type=aims].

The problem is that in that commit, you said to do no validation at all specific to Engineering Reports (including Executive Summary presence), but Ronald then overruled that, so in fact, the presence of Executive Summary is currently validated for. ... So, don't validate for the presence of any of them, I think you're now saying.

[ghobona]

@opoudjis It's ok to leave the Executive Summary validation in place.

[ghobona]

Revision history is not required.