Metanorma for OGC markup

Normative references

The “Normative references” section is named as titled and should occupy Clause 3.

In legacy OGC documents, it can be named just “References”.

Terms and definitions

== Terms and definitions
=== term 1
...
=== term 2
...

== Terms, definitions and symbols
=== Terms and definitions
==== term 1
...
==== term 2
...
=== Symbols
stem:[x + y]:: Notation one
stem:[x - y]:: Notation two
...

== Terms, definitions and abbreviated terms
=== Terms and definitions
==== term 1
...
==== term 2
...
=== Abbreviated terms
OGC:: Open Geospatial Consortium
ISO:: International Organisation for Standardisation
...

== Terms, definitions, symbols and abbreviated terms
=== Terms and definitions
==== term 1
Definition 1
==== term 2
Definition 2
=== Symbols
stem:[x + y]:: Notation one
stem:[x - y]:: Notation two
...
=== Abbreviated terms
OGC:: Open Geospatial Consortium
ISO:: International Organisation for Standardisation
...

== Terms and definitions
[.boilerplate]
=== My predefined text
Predefined content that overwrites the default one taking into
account that:
* The title "My predefined text" will not be shown in the output.
* This practice does not follow OGC requirements.

[appendix]
== Glossary
=== geospatial
relating to geographic and spatial information
[.source]
<<OGC21-017,clause="4.3">>
=== spatial
...

[appendix,heading=glossary]
== Customized glossary section
=== geospatial
relating to geographic and spatial information
[.source]
<<OGC21-017,clause="4.3">>

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):

• Abstract
• Executive summary (Engineering Reports only)
• Keywords
• Preface
• Security considerations [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v1.2.5]
• Submitting organizations
• Submitters

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].

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”.

.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].

.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]

.Setting the Preface

:received-date: 2019-01-01
== Preface
Your preface text...
=== Preface sub-clause
More preface text...

Keywords

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

Prefatory text is generated automatically.

.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”.

.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.

.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].

.Setting the Submitters section with OGC membership status

== Submitters
|===
|Name |Affiliation |OGC member
|Steve Liang | University of Calgary, Canada / SensorUp Inc. | Yes
|===

.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]

.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.

.Setting additional preface sections

== Preface
...
[.preface]
== Intended audience
...

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].

.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
...
|===

Example blocks

Unlike typical Metanorma, examples can have captions:

.Setting captions in an example

[example]
.Example caption
====
Text
====

Table blocks

Table cells under OGC always have a vertical alignment of middle [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v1.4.1].

Any markup instructions to set cell alignment to a different vertical alignment are ignored.

Unnumbered blocks

In Metanorma for OGC, all block elements are auto-numbered in order to facilitate unique referencing.

Each block label is unique and typically composed of the block type with a sequence number. For instance, “Table 3” or “Figure 5”.

In some cases, the author may want to remove the unique label and the numbering applied to a block, for example, when inserting short source code blocks within text that have no need of being uniquely referenced.

All auto-numbered blocks can be marked to not be labelled via the unnumbered attribute option.

These block types include:

• Figure
• Example
• Equation
• Source code
• Table

The unnumbered attribute can be used in the following ways, in equal effect.

For blocks without the explicit block type defined, prepend with the [%unnumbered] attribute right before the block definition.

[%unnumbered]
image::images/fig1.png[]

[%unnumbered]
[example]
Example content

[%unnumbered]
[stem]
++++
x = y + z
++++

[%unnumbered]
[source,json]
----
{
  "title": "Buildings in city",
  "description": "Access to data about buildings in the city via a Web API."
}
----

[%unnumbered]
[cols="2",options="header"]
|===
| header 1 | header 2
| cell 1 | cell 2
|===

For blocks with their types defined explicitly that do not have the options attribute list, insert "%unnumbered" right after the block type, before the block type separator, e.g.: [example%unnumbered], [stem%unnumbered], etc.

[example%unnumbered]
Example content

[stem%unnumbered]
++++
x = y + z
++++

[source%unnumbered,json]
----
{
  "title": "Buildings in city",
  "description": "Access to data about buildings in the city via a Web API."
}
----

For tables, we can add the unnumbered attribute as an option, e.g.: [cols="...",options="header,unnumbered"]

[cols="2",options="header,unnumbered"]
|===
| header 1 | header 2
| cell 1 | cell 2
|===

As a rule of thumb, if you are unsure how to remove the numbering of a block, just prepend [%unnumbered] to it. It works for any block that supports the unnumbered attribute.