Metanorma: Aequitate Verum

Metanorma for OGC

Typical sections in OGC

General

The easiest way to ensure that you are following the document structure that OGC demands, is to use a Metanorma template.

If you author a document type that doesn’t have a template, check a sample document for better understanding how to structure that document.

Typically, an OGC document contains the following content order:

Preliminary sections

General

The following clauses are preliminary elements, and are moved into the frontispiece of the document (in Metanorma, the “document preface”).

The OGC DocTeam has specified that all these elements are MANDATORY in OGC documents (in this order):

The Foreword and Introduction are not recognised as part of the document preface by default [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v1.0.2].

Note

Additional preliminary sections are allowed but not encouraged. There are two mechanisms for adding additional content as preliminary elements:

  1. Add their content in the Full Preface as additional sub-sections

  2. Add them as additional preliminary elements

Abstract

The abstract is recognized as the first clause with an abstract style attribute:

[abstract]
== Abstract

This standard describes a conceptual and logical model for the exchange
of groundwater data, as well as a GML/XML encoding with examples.

Executive summary

The “Executive summary” section is mandatory for OGC Engineering Reports. It is only allowed for that document type [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v1.5.3].

The Executive Summary section is entered as a clause with the title “Executive summary”.

Example 1. Setting the Executive summary through the predefined title
== Executive summary

This is the executive summary...

Alternatively, it can be explicitly declared if the title is different [executive_summary] [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v2.6.0].

Example 2. Setting the Executive summary through explicit declaration
[executive_summary]
== Executive summary, differently named

This is the executive summary...

Preface

A preface clause is recognized as a full section, with the title “Preface”. The Preface clause may contain subclauses. [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v1.0.1]

Example 3. Setting the Preface
:received-date: 2019-01-01

== Preface

Your preface text...

=== Preface sub-clause

More preface text...
Note
 Previously, the Preface section can be specified by text entered after a .Preface label, which has to be placed between the AsciiDoc document attributes and the first AsciiDoc section title. This behavior is now deprecated in favor of specifying the Preface as a real section to allow better reflection of content order.

Keywords

“Keywords” are entered as document attributes as :keywords:, with the value as a comma-delimited list.

Prefatory text is generated automatically.

Example 4. Setting the Keywords attribute
:keywords: ogcdoc, OGC document, groundwater, hydrogeology, GWML2

Security considerations

The Security considerations section is entered as a clause with the title “Security considerations”.

Example 5. Setting the Security considerations section
== Security considerations

The following security considerations apply...

If the security considerations are not provided in the source document, the clause is inserted with the text “No security considerations have been made for this standard.”

Submitting organizations

“Submitting Organizations” are entered using the :submitting-organizations: document attribute.

The values are entered using a semi-colon delimited list.

Prefatory text is generated automatically.

Example 6. Setting the Submitting organizations attribute
:submitting-organizations: Geological Survey of Canada (GSC), Canada; U.S. Geological Survey (USGS), United States of America

Submitters (and Contributors)

“Submitters” are entered using a table, contained in a section with the title “Submitters”.

In OGC Engineering Reports, "Submitters" is rendered as "Contributors". A title of "Contributors" is treated as equivalent to "Submitters" [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v2.3.14]. The "Contributors" section in an Engineering report can declared using the clause attribute [contributors].

Note
 Any table included in a Submitters section is automatically unnumbered [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v1.4.1]
Example 7. Setting the Submitters section with OGC membership status
== Submitters

|===
|Name |Affiliation |OGC member

|Steve Liang | University of Calgary, Canada / SensorUp Inc. | Yes

|===
Example 8. Setting the Submitters section without OGC membership status
== Submitters

All questions regarding this submission should be directed to the editor or the
submitters:

|===
|Name |Affiliation

|Boyan Brodaric |GSC
|Alexander Kmoch |U Salzburg

|===

Engineering report elements

Preliminary sections specific to Engineering Reports are entered by using the following clause attributes [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v2.6.0].

  • "Overview": [overview]

  • "Future outlook": [future_outlook]

  • "Value proposition": [value_proposition]

Note
 These clause declarations are equivalent to [.preface,type=…​], independent of the actual title provided.
Example 9. Setting Engineering Report preliminary elements
[overview]
== Overview

This is an Engineering Report overview.

[value_proposition]
== Proposed value

This is an Engineering Report value proposition.

== Initial clause

This is where the main section of the Engineering Report document begins.

Additional preliminary elements

The OGC DocTeam has specified that additional preliminary elements are allowed in OGC documents but not encouraged.

This is useful for document backwards-compatibility and cross-published standards at other SDOs.

Additional preliminary elements should be encoded under the [.preface] element, and they will be rendered after the five mandatory preliminary elements.

Note
 Functionality implemented in https://github.com/metanorma/metanorma-ogc/issues/83.
Example 10. Setting additional preface sections
== Preface

...

[.preface]
== Intended audience

...

Terms and definitions

The terms and definitions is used to define important terms and cite them throughout the standard.

Learn how to enter terms and definitions.

References

The references section contains normative references, it is considered a “bibliography” section.

Learn how to Entering bibliographic references.

Note
 In OGC there are commonly two “bibliography” sections. The “References” section for normative references, and the “Bibliography” section which is for informative references.

Content sections

After the sections above, any number of content sections can be added.

Annex sections

General

Annex sections are declared by prepending the [appendix] tag above the section declaration. Annexes can be added as necessary.

An annex can either be normative or informative. By default an annex is marked informative.

In order to declare a normative annex, use the obligation attribute in the following manner: [appendix,obligation=normative]

Example 11. Example of creating a normative versus an information annex
// Without declaration, an annex is informative.
[appendix]
== Informative annex title
...

// A normative annex.
[appendix,obligation=normative]
== Normative annex title
...

// A informative annex with explicit declaration
[appendix,obligation=informative]
== Informative annex title
...

Annex clauses are placed after all content sections, right before the bibliography section.

Glossary

OGC documents can contain an optional “Glossary” as an annex that provides terminology for informative purposes.

The Glossary section can contain terms imported from other documents only meant for illustrative purposes.

The Glossary section is recognised as an annex with the title “Glossary”, or marked up with [heading=glossary] [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v1.4.1].

The “Glossary” annex does not support symbols, abbreviations or other sections. Only terms and definitions are allowed. The terms are rendered in the same format as in the "Terms and definitions" clause.

The “Glossary” section, when exists, is placed as the last annex section before the “Revision history” section (if it exists).

Example 12. Markup structure of a Glossary annex containing terms and definitions
[appendix]
== Glossary

=== geospatial

relating to geographic and spatial information

[.source]
<<OGC21-017,clause="4.3">>

=== spatial
...

A glossary section with a customized name can be encoded as follows.

Example 13. Example of Glossary annex with custom name
[appendix,heading=glossary]
== Customized glossary section

=== geospatial

relating to geographic and spatial information

[.source]
<<OGC21-017,clause="4.3">>

Revision history

A “Revision History” is an optional section that contains description of changes per revision.

It is always placed as the last annex section if it exists. [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v2.0.1].

Note
 Currently, this section is not machine-readable. However, OGC has plans to make it so. For future compatibility, please encode the table in the format described in the example below.
Example 14. Example of the “Revision history” section from OGC 20-010
[appendix,obligation="informative"]
== Revision history

[options="header"]
|===
|Date |Release |Editor | Primary clauses modified |Description
|2020-06-04 |0.9.0 |C. Heazel |all |Draft for review
|2020-06-07 |0.9.1 |T. H. Kolbe |Chapter 10 |Bibliography was added
...
|===