Document header and metadata

General

The header contains information about the document (metadata). You specify these metadata by using predefined document attributes, that look like this:

:document-attribute: some-value

Most of the attributes take a value, while others are simple flags without a value, like:

:draft:

Some of the metadata will be visible in your document, such as :title:, while others are not visible but still affect how your document is generated.

The order of attributes does not matter to Metanorma.

You can specify metadata about:

Authors: issuing organization, authors, and their location
Document info: language, document stages (draft, published, etc.) copyright holder, etc.
Dates: draft dates, revision dates, publishing date, copyright year, etc.
Identifiers: document numbers, ISBNs, URIs (Uniform Resource Identifiers)

Note	Other metadata influence how the document is generated and should only be used by advanced users. Please refer to the OGC document attributes.

At a minimum, you will need to specify:

Title
Metanorma document class as ogc
Document number
Document type, and optionally subtype
Document stage
Committee
Author or editor

Note	Please refer to reference documentation to see the full list of OGC-specific document attributes.

Note	In this section we use the document header from OGC 17-069r3 to explain.

Document-specific attributes and basic operations

These are the basic document attributes for OGC.

Example 1. Setting basic document attributes for OGC

= API - Features - Part 1: Core (1)
:docnumber: 17-069r3 (2)
:external-id: http://www.opengis.net/doc/IS/ogcapi-features-1/1.0 (3)

OGC document title.
OGC document number.
OGC External ID for this deliverable.

These are operational concerns that are useful for the author.

:mn-document-class: must be set in order to set the flavor to OGC.
:mn-output-extensions: determines what output to be produced.

Example 2. Setting OGC-specific attributes

:mn-document-class: ogc (1)
:mn-output-extensions: xml,html,doc,pdf,rxl (2)
:local-cache-only: (3)

Metanorma flavor. For OGC, enter ogc.
Metanorma output formats. For OGC, supported formats are xml, html, pdf, doc and rxl.
Metanorma option to store data cache in the current directory.

Document types and subtypes

OGC offers many different types of deliverables that differ in the level of consensus.

Some types, such as standard and best-practice have subtypes that must be set.

The type is to be set via these two attributes:

:doctype: for the document type
:docsubtype: for the document subtype, necessary for certain :doctypes:

Document types, set using the :doctype: attribute, include:

standard: Standard (a document subtype is necessary) (default)
draft-standard: Draft Standard (a document subtype is necessary) [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v2.2.6]
abstract-specification-topic: Abstract Specification
best-practice: Best Practice (a document subtype is necessary)
change-request-supporting-document: Change Request Supporting Document
community-practice: Community Practice
community-standard: Community Standard
discussion-paper: Discussion Paper
engineering-report: Engineering Report
other: Note, Primer, etc.
policy: Policy, Policy — Name Type Specification
reference-model: Reference Model
release-notes: Release Notes
test-suite: Test Suite
user-guide: User Guide
white-paper: White Paper

Document subtypes, set using the :docsubtype: attribute, include:

For :doctype: set to standard or draft-standard:
- implementation: Implementation (default)
- conceptual-model: Conceptual model
- conceptual-model-and-encoding: Conceptual model and encoding
- conceptual-model-and-implementation: Conceptual model and implementation
- encoding: Encoding
- extension: Extension
- profile: Profile
- profile-with-extension: Profile with extension
For :doctype: set to best-practice:
- general: General (default)
- encoding: Encoding
- extension: Extension
- profile: Profile
- profile-with-extension: Profile with extension

Example 3. Setting document type and subtype

:doctype: standard (1)
:docsubtype: implementation (2)

OGC document type.
OGC document subtype. Not all OGC deliverables have subtype.

Document stages and progress dates

OGC deliverables go through various stages of consensus building.

The document stage is set via the :status: attribute.

Values accepted by the :status: attribute include:

For an OGC standard, an OGC draft standard, and an abstract specification topic, it goes through the stages of: swg-draft, oab-review, public-rfc, tc-vote and approve.
An OGC community standard goes through the same stages as a normal standard, except swg-draft is replaced with work-item-draft.
All other types only have one draft stage and then goes to approved.
OGC deliverables can also be rescinded or retired but these are not discussed here.

Example 4. Setting document stage and progress dates

:edition: 1.0 (1)
:status: approved (2)
:received-date: 2019-07-11 (3)
:issued-date: 2019-09-09 (4)
:published-date: 2019-10-14 (5)

OGC document edition. This is optional.
OGC document status.
OGC date of receipt.
OGC date of issuance.
OGC date of publication.

Authorship and other preface information

There are three types of authorship information:

The working group that created the document, this is set via the :committee: attribute.
The individual contributors that created the document, this is set via the :fullname: and :role: attributes. Additional contributors are set by suffixing the attribute with a _{n} where {n} is a sequential number after 1, e.g. For :fullname_2: use :role_2:.
The submitting organizations (active OGC members) that submitted this document (i.e. supported the adoption of the document), this is set via the :submitting-organizations: attribute as semicolon-delimited values.

Example 5. Usage of authorship information

:committee: technical (1)
:fullname: Clemens Portele (2)
:fullname_2: Panagiotis (Peter) A. Vretanos
:fullname_3: Charles Heazel
:role: editor (3)
:role_3: editor
:keywords: OGC API, ISO, ISO/TC 211, geographic information, Geospatial API (4)
:submitting-organizations: CubeWerx Inc.; Heazeltech LLC; Hexagon; ... (5)

OGC committee. Typically technical for standards.
Name of the individual contributor (author or editor).
Role of author or editor. To set role of a :fullname_2: use :role_2:. If the role value is not provided, it is set to author by default.
List of OGC keywords, comma-delimited.
List of OGC members submitting this deliverable, semicolon-delimited.

Metadata references

Metadata defined as document attributes can be used to substitute values defined by putting the attribute in curly braces {attribute}. The reference will be replaced with the value in the rendered output.

Example 6. Using a document attribute for variable replacement

:architecture-dwg: OGC Architecture Domain Working Group

This document was prepared by the {architecture-dwg}.

renders as:

This document was prepared by the OGC Architecture Domain Working Group.

Document history

Semantic markup of document history can be added to the document, using Metanorma extension and Relaton YAML [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v2.5.0]. Document history is realised as a final "Revision history" annex.

The official structure for document history is as follows:

Date: represented as date, with type published, updated (modifications to document), or issued (circulated drafts).
Release: represented as edition, or version/draft.
Author: represented as one or more contributor objects, following Relaton YAML. The role of the contributor can be specified optionally, as role/type, to differentiate editors from the default role of author.
Paragraph modified: represented as amend/location, with locality specified as in bibliographic cross-references; note that whole is used in Relaton to specify the entire document (and will be rendered as "all" in the generated document).
Description: represented as amend/description, can contain inline and block Asciidoc markup.

The following is an illustration of semantic document history markup for OGC.

[.preface]
== Misc-container

=== document history

[source,yaml]
----
- date:
  - type: published
    value:  2012-04-02
  version:
    draft: Draft
  contributor:
    person:
      name:
        completename: R Thakkar
  amend:
    location: whole
    description: Original draft document
- date:
  - type: published
    value:  2002-08-30
  version:
    draft: 0.1 02-077
  contributor:
    - person:
       name:
          completename: Kurt Buehler
       role:
         type: editor
    - person:
       name:
          completename: George Percivall
       role:
         type: editor
    - person:
       name:
          completename: Sam Bacharach
       role:
         type: editor
    - person:
       name:
          completename: Carl Reed
       role:
         type: editor
    - person:
       name:
          completename: Cliff Kottman
       role:
         type: editor
    - person:
       name:
          completename: Chuck Heazel
       role:
         type: editor
    - person:
       name:
          completename: John Davidson
       role:
         type: editor
    - person:
       name:
          completename: Yaser Bisher
       role:
         type: editor
    - person:
       name:
          completename: Harry Niedzwiadek
       role:
         type: editor
    - person:
        name:
          completename: John Evans
        role:
         type: editor
   - person:
        name:
          completename: Jeffrey Simon
       role:
         type: editor
  amend:
    description: Initial version of ORM. Doc OGC
- date:
  - type: published
    value:  2018-06-04
  version:
    draft: 1.0
  contributor:
    person:
      name:
        completename: Gabby Getz
  amend:
    description: |
      * Put _3D Tiles_ specification document into OGC document template
      * Miscellaneous updates
----