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:
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):
Executive Summary (Engineering Reports only)
Security Considerations [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v1.2.5]
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].
The abstract is recognized as the first clause with an
[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.
The Executive Summary section is entered as a clause with the title “Executive summary”.
== 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].
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...
Previously, the Preface section can be specified by text entered after a
“Keywords” are entered as document attributes as
:keywords:, with the
value as a comma-delimited list.
Prefatory text is generated automatically.
:keywords: ogcdoc, OGC document, groundwater, hydrogeology, GWML2
The Security considerations section is entered as a clause with the title “Security considerations”.
== 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” are entered using the
The values are entered using a semi-colon delimited list.
Prefatory text is generated automatically.
:submitting-organizations: Geological Survey of Canada (GSC), Canada; U.S. Geological Survey (USGS), United States of America
“Submitters” are entered using a table, contained in a section with the title “Submitters”.
|Any table included in a Submitters section is automatically unnumbered [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v1.4.1]|
== Submitters |=== |Name |Affiliation |OGC member |Steve Liang | University of Calgary, Canada / SensorUp Inc. | Yes |===
== 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
element, and they will be rendered after the five mandatory preliminary
Functionality implemented in https://github.com/metanorma/metanorma-ogc/issues/83.
== 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.
The references section contains normative references, it is considered a “bibliography” section.
Learn how to enter bibliographic entries.
|In OGC there are commonly two “bibliography” sections. The “References” section for normative references, and the “Bibliography” section which is for informative references.|
After the sections above, any number of content sections can be added.
Annex sections are declared by prepending the
[appendix] tag above the section
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:
// 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.
OGC documents can contain an optional “Glossary” as an annex that provides terminology for informative purposes.
The Glossary section is recognised as an annex with the title “Glossary”,
or marked up with
[heading=glossary] [added in
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).
[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.
[appendix,heading=glossary] == Customized glossary section === geospatial relating to geographic and spatial information [.source] <<OGC21-017,clause="4.3">>
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].
|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.|
[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 ... |===