Metanorma: Aequitate Verum

Metanorma for OGC

Terms and definitions

General

Every OGC standard requires a “Terms and definitions” clause to hold terminology entries important to the standard.

The “Terms and definitions” section provides a single point of truth for terms and concepts used within this standard. Content in the “Terms and definitions” section is considered normative.

Optionally, if there are informative terminology entries, OGC allows a “Glossary” section to be set in an Annex, which only consists of informative terms.

Note
 OGC has recently adopted similar practice to that of ISO with regards to the “Terms and definitions” clause.

Terminology models

Terminology entries in OGC and ISO adhere to the terminology model from the international standard for terminology representation, ISO 10241-1.

The organization of terminology entries within the section should follow the defined conceptual hierarchies specified in ISO 704.

Terminology clauses

Normative terms are to be kept in the “Terms and definitions” clause, which is always to be located at Clause 3.

Note
 Legacy practice may have this clause at Clause 4, but in new publications this is not allowed.
Defining the Terms and definitions section
== Terms and definitions

...
Defining the Glossary section
[appendix,obligation="informative"]
[heading='terms and definitions']
== Glossary

...
Note
 The initial notice in Terms and Definitions clauses ("This document uses the terms defned in OGC Policy Directive 49…​") is inserted automatically by Metanorma, and you should not type it in to your document.

Entering terminology entries

There are in general three kinds of terms:

  • Terms that are newly defined in this standard;

  • Terms that are entirely sourced from another document;

  • Terms that are sourced from another document but modified within this standard.

A newly defined term:

=== milled rice
alt:[white rice] (1)

{{husked rice}} from which almost all of the bran and embryo have been removed by milling. (2)

  1. alt:[white rice] indicates the alternative term for milled rice. Metanorma uses both the notations alt:[] and admitted:[], and normally refers to this as an admitted term (the terminology of ISO); they mean the same thing.

  2. {{husked rice}} cites a previously introduced term.

A sourced term:

=== extraneous matter
alt:[EM]
domain:[rice] (1)

organic and inorganic components other than whole or broken kernels

[example] (2)
Foreign seeds, husks, bran, sand, dust.

[.source]
<<ISO7301,clause 3.3>> (3)

  1. Terms can be specified to a certain domain.

  2. If you provide an example, use the [example] attribute.

  3. Term is sourced but no modification is done.

A sourced but modified term looks like this:

=== husked rice (1)
deprecated:[cargo rice] (2)

Paddy from which the husk only has been removed. (3)

[.source] (4)
<<ISO7301,clause 3.2>>, The term "cargo rice" is shown as deprecated, and Note 1
to entry is not included here

  1. The term that should be defined is marked as a subheading under the terms and definitions section.

  2. The term husked rice supersedes cargo rice. To document the old term, use the annotation deprecated:[term].

  3. Definition for the term: the first paragraph of text after commands like deprecated:[] and alt:[].

  4. The [.source] attribute indicates that a citation follows, indicating where the term definition has been taken from. Make sure to include the dot . before source, so that the citation will be rendered correctly.

More OGC terms and definitions

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.

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