Metanorma: Aequitate Verum

Metanorma for OGC

Bibliographic references

General

Standard documents typically contain bibliographic references, and those references are usually presented in two categories:

  • Normative references

  • Informative references

In OGC deliverables, bibliographic references are put into these two sections:

  • “Normative references”, contain normative references, located at Clause 3;

  • “Bibliography”, contain informative references, placed as the last Annex.

Creating a bibliographic section

Every bibliographic section must be preceded by the style attribute [bibliography] so that bibliographic references are recognized as such.

Place them into the Normative references if they are a required part of this standard.

[bibliography]
== Normative references

* [[[OGC_07-011,OGC 07-011]]], OGC: The OGC Abstract Specification Topic 6: Schema for coverage
geometry and functions, OGC Document 07-011, 2006. (Also available as ISO 19123)
http://portal.opengeospatial.org/files/?artifact_id=19820

Or if the references are informative,

[appendix]
[bibliography]
== Bibliography

* [[[OGC_08-094,OGC 08-094r1]]], OGC: OGC SWE Common Data Model Encoding Standard, OGC
Document 08-094r1, version 2.0, 2011 http://portal.opengeospatial.org/files/?artifact_id=41157

Entering a bibliographic entry

Bibliographic references (citations) are entered using a specialized list syntax.

  1. Starts with a list item indicator (*).

  2. Followed by a pair of triple square brackets ([[[ …​ ]]]) which contains

    • A unique anchor name used to reference this entry. This anchor has to be unique per document.

    • A document identifier (also called the “reference tag”) that identifies this reference to the reader. If the cited document is a standard, it is likely that Metanorma can automatically fetch bibliographic information for it via Relaton.

      Note
      		 If Metanorma recognizes a document identifier, it will overwrite any title you provide with the authoritative title of the reference.

  3. After the triple brackets, the citation text is entered manually. OGC uses the Springer LNCS bibliographic style, which is now officially called the "Springer MathPhys style" (guidelines).

Syntax for a bibliographic entry
* [[[{anchor},{document identifier}]]], _citation text_
Example 1. Example of an auto-fetched entry

The following two statements will create identical outputs.

* [[[OGC_08-094,OGC 08-094r1]]]
* [[[OGC_08-094,OGC 08-094r1]]], OGC: OGC SWE Common Data Model Encoding Standard, OGC
Document 08-094r1, version 2.0, 2011 http://portal.opengeospatial.org/files/?artifact_id=41157

Referencing a bibliographic entry

There are two ways to cite a bibliography entry entered in the bibliography sections.

  1. Cite the whole document, by cross-referencing the anchor name like this: <<OGC_08-094>>.

  2. Cite a particular locality of the document, by cross-referencing the anchor name but additionally specify a locality as the second argument, like this: <<OGC_08-094,part=IV,chapter=3,paragraph=12>>.

Bibliography example

The following source code illustrates how a bibliography section looks like in Metanorma AsciiDoc.

Example 2. Example for a bibliography section
[bibliography]
== Normative references

* [[[ISO20483,ISO 20483:2013]]], _Cereals and cereal products -- Determination of moisture content -- Reference method_

* [[[ISO6540,ISO 6540:1980]]]. _Maize -- Determination of moisture content (on milled grains and on whole grains)_

Gets rendered as:

  • ISO 20483:2013. Cereals and cereal products — Determination of moisture content — Reference method

  • ISO 6540:1980. Maize — Determination of moisture content (on milled grains and on whole grains)

Auto-fetching OGC references

Relaton fetches bibliographic entries for OGC documents, when the syntax matches the following:

  • OGC {identifier} (e.g. OGC 14-083r2)

  • OGC(identifier) (e.g. OGC(14-083r2))

If Relaton can resolve the reference, the bibliographic information from the database will be rendered.

Example 3. Example of a OGC standard reference
* [[[OGC12-080r2,OGC 12-080r2]]]

will render:

Roger Brackin, Pedro Gonçalves: OGC 12-080r2, OGC OWS Context Conceptual Model. Open Geospatial Consortium (2014). Available at: https://portal.ogc.org/files/?artifact_id=55182

If Relaton cannot resolve the reference, the provided description will be rendered.

Example 4. Example of a non-auto-fetched reference
* [[[GeoRSS,GeoRSS]]], GeoRSS Geographically Encoded Objects for RSS Feeds. (http://www.georss.org/)

will render:

GeoRSS Geographically Encoded Objects for RSS Feeds. (http://www.georss.org/)