Implement Metanorma for OGC documents

[ronaldtse]

Document types

Standards

• Standard (with or without Compliance Suite)
  • Implementation Standard
  • Abstract Specification
  • Community Standard
  • Profile
• Best Practices Document

Others

• Engineering Report
• Discussion Paper
• Whitepaper
• User Guide
• Technical Committee Policy Directive
• "Informative/Educational" (?), such as "OGC Reference Model 08-062r7"

Deliverable stages

• SWG Work
• OAB Review
• OGC-NA Review
• Public Review
• Prepare for Approval
• TC Approval to Vote
• TC Vote
• PC Vote

(Will seek clarification on document stage codes)

Versioning

A semantic versioning is necessary. e.g. 1.0, 1.1, 2.0, etc. Maybe this is the "edition"?

Example deliverables

Despite differences in appearance (now), all of these should be presented according to the standard "Standard" format.

Standard: WCS

Standard: WKT

Non-standard: Testbed

Non-standard: GeoPackage

Non-standard: Ref model

[opoudjis]

There was nothing I could find on the website that looked clearly like a specification of how to write documents, but there are clearly undocumented conventions, e.g. that there is a Conformance statement between Scope and References, that References are not called Normative References, and that there is no separate Bibliography. The standards, at least, seem to stick close to ISO style.

OGC are going to have to flesh out their information model.

[ronaldtse]

@opoudjis from experience, having specifications for deliverables in standards bodies, is the exception not the norm.

We will have to help them "standardize" the conventions into an information model.

[ronaldtse]

@opoudjis they have a specification and templates provided in this document:

https://portal.opengeospatial.org/files/?artifact_id=40077

[ronaldtse]

OGC TC procedures (and document types): http://docs.opengeospatial.org/pol/05-020r24/05-020r24.html

[opoudjis]

I am modelling submission date as created-date, which is defined in the metanorma-standoc Readme as "The date on which the first version of the standard was created". This is not updated-date, "The date on which the current version of the standard was updated", nor circulated-date, "The date on which the unpublished standard was last circulated officially as a preprint. For standards, this is associated with the latest transition to a formally defined preparation stage, such as Working Draft or Committee Draft".

@ronaldtse Should I create a new "received-date", for when the document was first received by the standards body, or is created-date good enough, since noone cares about document being created until it is viewed by someone other than the author?

[ronaldtse]

@opoudjis where's the "received-date" specified? I don't see them in the templates...

[opoudjis]

It doesn't exist yet. That's why I'm asking whether I should make it up, or use created-date.

[ronaldtse]

I see, you mean the method of encoding the "submission date". Can't we just have a "submission-date"? "Submission" can mean so many things -- submission to a stage, submission to the body, submission by the editor...

[opoudjis]

... Which is precisely why we shouldn't use it. The dates should be clear in meaning if they can be.

1. Can we find out what OGC mean by it?

2. Do you want submitted-date, then? And if so, what is the formal definition of submitted-date? The date at which the document is received by the standards body for processing, with no further definition?

[ronaldtse]

In the OGC TC process document, I can see the word “submit” being related to submitting an RFC (a proposal), submitting a “Candidate Standard” and a Full Standard.

I assume that’s the meaning of “submission date”, which is the date a document was processed into the OGC system. So maybe “received-date” is the closest.

We need to seek clarification on it.

[opoudjis]

https://github.com/opengeospatial/D012-MapML_Engineering_Report shows that the Engineering Report subgroup have a well-defined asciidoctor document header template, which I am making backward compatible with the Asciidoctor processor.

http://external.opengis.org/twiki_public/ERGuidance/WebHome does not have a pointer to this asciidoctor template. Please ensure that OGC provide all comparable asciidoctor templates for their different document types where they exist, with online locations for them (so the readme can reference them). OGC truly do have a document model, they just haven't surfaced it somewhere accessible.

[ronaldtse]

@opoudjis there should only be one presentation style, we should NOT adopt all different styles for different document types.

They want standardization, not specialization. The current situation is what they don’t want.

[ronaldtse]

And we will be designing a new presentation style for them. Their current style probably works best with the Doc or PDF output.

[opoudjis]

Still need to see what asciidoc templates they already have in place; goes to establishing their document model, and would like our tool to be backward compatible with them.

[ronaldtse]

What does “backwards compatible” mean in this context?

[ronaldtse]

BTW notice that the latest D012 document uses a structure similar to ISO:

• 1 contains Foreword (amidst other things)
• 2 are normative references
• 3 are terms
• bibliography is at the end

I was told they want to harmonize their structure with ISO since they often submit to ISO.

[opoudjis]

What does “backwards compatible” mean in this context?

They can use their current asciidoctor with our gem.

[opoudjis]

BTW notice that the latest D012 document uses a structure similar to ISO:

Oh, a lot of their docs are, except that they usually inject a Conformance clause between Scope and References.

[ronaldtse]

But (at least) most of their stuff:

• Don't have the metadata document attributes
• Have a non-conformant Foreword, don't have a Scope
• Annexes are not coded as [appendix]

[ronaldtse]

If we want to be backwards compatible, we will need to infer the document attributes (which is so fuzzy) and from titles.

It'll be easier if we have a new script (a one-time script) that specifically converts their old stuff to the new format?

[ronaldtse]

OGC 10-177r2: Guidance to Editors and Authors of OGC Documents that use the OGC Standards document template.

OGC_Standard_Document_template_guidance_on_use..pdf

[opoudjis]

Work to go from Standards template:

• Placement of preliminary elements in the document preface: Abstract, Keywords, Preface (= Foreword), Submitting Organizations, Submitters. Incorporation into Grammar.
• Make Scope, Conformance, References, Terms mandatory for standards
• Allow Normative References to be called References.
• Indexes of figures, tables, and requirements (although perhaps OGC should be coding that, as an exercise: ISO used to require these, but it has presumably stopped doing so in practice.)

[opoudjis]

Done preliminary elements .

[opoudjis]

Done validation mandatory sections for standards. Done naming of references.

[ronaldtse]

Thanks @opoudjis !

[opoudjis]

Remaining task is https://github.com/riboseinc/metanorma-ogc/issues/7