Author OGC documents using Metanorma

General

The rendering of OGC documents has changed over the years. Metanorma formats OGC documents following current practice:

• All body text is left justified, with no exceptions allowed.

• Where section obligations are named (i.e. in annex names), they are only given as “normative” or “informative”; the alternate text of “non-normative” is disallowed.

• Ordered lists follow ISO style numbering, i.e. “a), b), c) …​”, with no exceptions allowed.

Inline formatting

Metanorma-OGC supports highlighting of text [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v1.2.16]:

This is #text to be highlighted#.

Sections

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

General

The “Terms and definitions” clause for current OGC documents adhere mostly to the ISO terms and definitions practices.

An OGC "Terms and definitions" section can be specified in the following ways:

• Standalone terms and definitions

• Combined terms, definitions and symbols

• Combined terms, definitions and abbreviated terms

• Combined terms, definitions, symbols and abbreviated terms

Note	The combined clauses feature is similar to that of the ISO combined terms and definitions clauses.

Note	This section supplements Concepts, designations, terms and definitions in general Metanorma documentation.

Standalone terms and definitions

If the clause contains only terms and definitions. The clause title will be set to “Terms and definitions”.

Example 1. Markup of simple "Terms and definitions" clause

== Terms and definitions

=== term 1
...

=== term 2
...

Combined terms, definitions and symbols

If the clause contains terms and definitions, together with a list of symbols.

The clause title will be set to “Terms, definitions and symbols”.

Example 2. Markup of "Terms and definitions" clause with symbols

== Terms, definitions and symbols

=== Terms and definitions

==== term 1

...

==== term 2
...

=== Symbols

stem:[x + y]:: Notation one
stem:[x - y]:: Notation two
...

Combined terms, definitions and abbreviated terms

If the clause contains terms and definitions, together with a list of abbreviated terms.

The clause title will be set to “Terms, definitions and abbreviated terms”.

Example 3. Markup of "Terms and definitions" clause with abbreviated terms

== Terms, definitions and abbreviated terms

=== Terms and definitions

==== term 1

...

==== term 2
...

=== Abbreviated terms

OGC:: Open Geospatial Consortium
ISO:: International Organisation for Standardisation
...

Combined terms, definitions, symbols and abbreviated terms

If the clause contains a subclause named "Terms and definitions", "Symbols" and "Abbreviated terms", then the clause title will be set to “Terms, definitions, symbols and abbreviated terms”.

Example 4. Markup of "Terms and definitions" clause with symbols and abbreviated terms

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

Note	Section titles are rendered in sentence-case, i.e. only the first letter of the first word is capitalized.

Modifying introductory text in "Terms and definitions"

A default OGC introductory text is inserted at the beginning of the clause in accordance to OGC policies.

As described in generic terms and definitions documentation, this text can be overridden by using the [.boilerplate] attribute applied to the first subclause.

Example 5. Overriding introductory content in the "Terms and definitions" section

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

Glossary for informative terms

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

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

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

Note	Additional preliminary sections are allowed but not encouraged. There are two mechanisms for adding additional content as preliminary elements: Add their content in the Full Preface as additional sub-sections 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 8. 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 9. 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 10. 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 11. 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 12. 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 13. 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 14. Setting the Submitters section with OGC membership status

== Submitters

|===
|Name |Affiliation |OGC member

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

|===

Example 15. 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 16. 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 17. Setting additional preface sections

== Preface

...

[.preface]
== Intended audience

...

Annex sections

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

Blocks

Example blocks

Unlike typical Metanorma, examples can have captions:

Example 19. 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 figure using "[%unnumbered]"

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

Unnumbered example using "[%unnumbered]"

[%unnumbered]
[example]
Example content

Unnumbered equation using "[%unnumbered]"

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

Unnumbered source using "[%unnumbered]"

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

Unnumbered table using "[%unnumbered]"

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

Unnumbered example by appending "%unnumbered" to block type

[example%unnumbered]
Example content

Unnumbered equation by appending "%unnumbered" to block type

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

Unnumbered source by appending "%unnumbered" to block type

[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"]

Unnumbered table by adding "unnumbered" in the "options" attribute list

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