Update document to latest Metanorma practices

[ronaldtse]

There are certain requirements that are not linked to corresponding conformance tests and vice versa, I did not have time to check them yet. So this is FYI @cnreediii @cmheazel for now.

Requirements: (ID rec-1): Requirement /rec/core/uri-external-use has no corresponding Conformance test
Requirements: (ID per-1): Requirement /per/core/informational-content-in-core has no corresponding Conformance test
Requirements: (ID per-2): Requirement /per/core/external-vocabs-core has no corresponding Conformance test
Requirements: (ID per-3): Requirement /per/core/repeated-requirements has no corresponding Conformance test
Requirements: (ID per-4): Requirement /per/core/abstract-superclass has no corresponding Conformance test
Requirements: (ID per-5): Requirement /per/core/conf-class-paramterized has no corresponding Conformance test
Requirements: (ID req-15): Requirement /req/core/conf-class-test-req-class has no corresponding Conformance test
Requirements: (ID rec-2): Requirement /rec/core/parallel-structure has no corresponding Conformance test
Requirements: (ID rec-3): Requirement /rec/core/circular-dependencies has no corresponding Conformance test
Requirements: (ID rec-4): Requirement /rec/core/simple-core has no corresponding Conformance test
Requirements: (ID per-6): Requirement /per/core/core-type has no corresponding Conformance test
Requirements: (ID per-7): Requirement /per/core/req-class-another-standard has no corresponding Conformance test
Requirements: (ID rec-5): Requirement /rec/core/optional-tests has no corresponding Conformance test
Requirements: (ID per-8): Requirement /per/core/core-maybe-recommendations has no corresponding Conformance test
Requirements: (ID ats_req-in-only-one-req-class): Conformance test /conf/core/req-in-only-one-req-class has no corresponding Requirement
Requirements: (ID ats_requirements-are-in-class): Conformance test /conf/core/reqs-are-in-class has no corresponding Requirement

Best practice changes:

• Metanorma is particular about semantic encoding, so the right syntax needs to be used.
• OGC has a defined set of allowed doctype and docsubtype values. Please refer to document attributes documentation.
• The :submitting-organizations: attribute is for entering "submitting organizations" (i.e. OGC members), semicolon-delimited (see Submitting organizations). Individual "submitters" are encoded in the preface (see Submitters).
• Cross-references between terms is called "concept mentions" which makes referencing terms very easy (see blog)
• Encoding of terms and their sources need to follow a particular syntax. Please refer to documentation on OGC Terms and definitions.
• Bibliography supports auto-fetch of not only standards, but also through ISBN that can be resolved via OpenLibrary. Two existing non-standards have been switched to ISBN fetching.
• Document structure (esp. Preface sections). OGC DocTeam has defined requirements for document structures of different doctypes. Please refer to the requirements and it is done at Sections required) (I've already migrated them)
• Cross-references to requirements should use the xref:{uri}[] syntax to directly cite the requirement (or permission or requirements class or conformance test or conformance class), instead of creating a manual anchor and citing the clause that contains the requirement. (I've migrated all)
• Requirements encoding in Metanorma supports a "title". In Annex A, I noticed that every conformance test (ATS_*) is given a special subclause, with what is technically the title of the test, those should be encoded in the conformance tests directly. However... Requirements currently have no name/clause assigned to them, but only a URI + description. I have migrated this content with requirement names that I find reasonable with, so the editors need to update them to your liking.

If desired, we can also update the other 2 parts in the repository to use the latest best practices. Let me know!

[ronaldtse]

This is how the document looks like now:

• document.pdf

[cnreediii]

@ronaldtse Thanks for providing the PDF for a reference. Right now I am making some suggested edits to main based on your comments.

One question: For the PDF version, is it possible not to list all the requirements etc in a table at the beginning? Folks asked that this be removed. Same goes for list of tables etc. Finally, is it possible not to have the full blue pages between major sections? I think these should be optional. They distract the reader from the flow of the document. The HTML document does not have these artifacts which is fine.

[ronaldtse]

@cnreediii these issues have to do with the document layout as approved by the DocTeam, and we need OGC approval to address them. (ping @ogcscotts @ghobona @gbuehler )

For the PDF version, is it possible not to list all the requirements etc in a table at the beginning? Folks asked that this be removed. Same goes for list of tables etc.

These are optional but are enabled for OGC by default, as approved by DocTeam.

https://www.metanorma.org/author/ref/document-attributes/

This is the ticket to track this task of allowing optional omission of these sections :

• Mechanism to turn off :toc-tables:, :toc-figures:, :toc-requirements: metanorma/metanorma-ogc#871

Finally, is it possible not to have the full blue pages between major sections? I think these should be optional. They distract the reader from the flow of the document. The HTML document does not have these artifacts which is fine.

This has to do with the approved PDF document layout. I assume this needs to be a DocTeam decision -- whether to keep the full pages between or not?