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, you can look at a sample document for better understanding how to structure that document.

Typically, an OGC document contains:

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 entered as a clause with the title “Executive Summary”.

EXAMPLE:

== Executive Summary

This is the executive summary...

This clause is mandatory for Engineering Reports, and only allowed for that document type [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v1.5.3].

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]

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

:keywords: ogcdoc, OGC document, groundwater, hydrogeology, GWML2

Security Considerations

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

EXAMPLE:

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

:submitting-organizations: Geological Survey of Canada (GSC), Canada; U.S. Geological Survey (USGS), United States of America

Submitters

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

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:

== Submitters

|===
|Name |Affiliation |OGC member

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

EXAMPLE:

== Submitters

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

|===
|Name |Affiliation

|Boyan Brodaric |GSC
|Alexander Kmoch |U Salzburg
|===

Additional preliminary elements

The OGC DocTeam has specified that additional preliminary elements are allowed 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.

EXAMPLE:

== Preface

...

[.preface]
== Intended audience

...

Terms and definitions

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

References

The refernces section contains normative references, also known as a bibliography section.

Content sections

After all the preliminary sections, and the terms and definitions section, you may add as many content sections as you need.

Annex

Annex clauses are declared by prepending the [appendix] tag to the clause. You can add as many annexes as you need.

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

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

[appendix,obligation=normative]
== Normative appendix title
...

// Default case; "obligation=informative" markup can be omitted.
[appendix,obligation=informative]
== Informative appendix title
...

The annex clauses allocate in the last position of the main content right before the bibliography clause.

Glossary as an appendix

A glossary in an OGC document is an annex with the same content as a “Terms and definitions” section, but with informative rather than normative effect.

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

EXAMPLE:

[appendix]
== Glossary

=== geospatial

relating to geographic and spatial information

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

EXAMPLE:

[appendix,heading=glossary]
== Customized glossary section

=== geospatial

relating to geographic and spatial information

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