Metanorma for IHO markup

Clause structure

IHO M-3, "Principles and procedures for making changes to IHO technical standards and specifications" (2/2007 as amended) is the general requirement document for IHO publications.

While IHO does not have stringent requirements for the internal structure of its publications, there is a general "best practice" pattern as derived from modern IHO publications.

Note	This pattern is derived from IHO S-102.

Preface segments
- Document History
1. Overview
- 1.1. Introduction
- 1.2. References
- 1.3 Terms, definitions and abbreviations
- 1.3.1 Use of language
- 1.3.2 Terms and definitions
- 1.3.3 Abbreviations
- 1.4 Publication metadata (abstract, title, change procedures etc.)
2 and onwards. Document content.
Annex A onwards. Document content.

Preface segments

Document History

The document history of the publication is marked up as a table.

Example 1. Example of Document History encoding (IHO S-102)

[.preface]
== Document History

[%unnumbered]
[cols="a,a,a,a",options="headers"]
|===
|Version Number |Date |Approved By |Purpose

|1.0.0
|April 2012
|TSMAD
|Approved edition of S-102

...
|===

Automatic generated content

The templated material ("boilerplate") of the document front matter is all automatically provided by Metanorma:

Cover page: IHO contact information.
Inner cover: Copyright statement.

Participants and contributors

General

An IHO publication is typically created by a working group that belongs to a committee.

Please refer to the document attributes on document contributors, on how they are specified.

Committee

Metanorma supports IHO publications developed under two committees:

HSSC. The Hydrographic Services and Standards Programme (Programme 2 of the IHO Work Programme).
IRCC. The Inter-Regional Coordination Committee (Programme 3 of the IHO Work Programme).

Working group

Under the IHO committees, there are many regional bodies or working group, or sub-working groups. All these groups are considered "working groups" in Metanorma.

Please refer to the full list at the respective committee sites: * HSSC * IRCC

Overview

General

The Overview clause, and its subclauses are recognized automatically from the supplied clause headers.

The subclauses recognized include:

Introduction
References
Terms, definitions and abbreviations

Introduction

The introduction of the document is marked up as a clause with the title "Introduction" within "Overview".

References

The introductory paragraph for normative references and bibliographies is automatically generated by Metanorma.

References are automatically sorted by Metanorma:

Normative references are automatically sorted by designator.
Bibliography references are automatically sorted by designators or author and title.

Example 2. Example of References clause (S-102)

[bibliography]
=== References
* [[[iho-s100,IHO S-100]]]

* [[[iho-s44,IHO S-44]]]

* [[[iho-s4,IHO S-4]]]

Definitions clause

General

Definitions are recognised as a clause with the title "Definitions" or "Terms and definitions".

Definitions are automatically sorted by Metanorma.

The notation for subdefinitions and cross-references in Metanorma is demonstrated in the following example.

Metanorma supports concepts, which capture terms are cross-referencable entities, including cross-references within the Definitions sections.

Note	Highlighting and cross-referencing of concepts is not supported in Metanorma for IHO as they are not defined in IHO.

Example 3. Example with abbreviated term, multiple definitions and concept relations

=== widget
preferred:[WgT]
related:contrast[thing] // Contrast:
related:seealso[whatsit] // See also:

[.definition]
device performing an unspecified function.

[.definition]
general metasyntactic variable.

renders as:

widget (WgT): (A) device performing an unspecified function. (B) general metasyntactic variable. See also: whatsit. Contrast: thing.

Multiple definitions

IHO documents supports multiple definitions per term.

Each definition is encoded using the [.definition] block.

Example 4. Example with multiple definitions (IHO Style Manual 2021)

=== output

[.definition]
Data that has been processed.

[.definition]
The process of transferring data from an internal storage device to an external
storage device.

renders as:

output: (A) Data that has been processed. (B) The process of transferring data from an internal storage device to an external storage device.

Concept relations

Synonyms

Synonyms are entered using preferred:[…] or admitted:[…].

A preferred term is intended to introduce equally valid term designations, such as abbreviations and acronyms such as acronyms. Preferred terms are encoded preferred[...]. These are displayed in parentheses after the initial term.

An admitted term is intended for synonyms. Admitted terms are encoded using admitted:[...]. These are displayed using the concept relation See:, where an additional term is automatically inserted into the clause.

Note	See: terms are the opposite relations to Syn: relations, and the generated relation will point the See: term’s definition back at the original term. Please do not manually insert markup for See: terms.

Example 5. Example of definition with See: (IHO Style Manual 2021)

=== coded character set
admitted:[code set]

A set of characters for which coded representation exist.

renders as:

code set: See: coded character set.

coded character set: A set of characters for which coded representation exist. Syn: code set.

Example 6. Example of definition showing preferred abbreviation and admitted term as See:

=== widget
preferred:[WgT]
admitted:[doovywhack]

device performing an unspecified function.

renders as:

doovywhack: See: widget.

widget (WgT): device performing an unspecified function. Syn: doovywhack.

Contrast

A contrasting term is one that describes an opposite meaning to the designated definition.

Example 7. Term encoded with Contrast: (IHO Style Manual 2021)

=== input reference axis
related:contrast[output reference axis]

The direction of an axis as defined by the case mounting surfaces, external case
markings, or both.

renders as:

input reference axis: The direction of an axis as defined by the case mounting surfaces, external case markings, or both. Contrast: output reference axis.

Equivalence

An equivalent term is meant to cross-reference pre-existing term definitions.

Equivalent terms are encoded using the relation related:equivalent[…].

Term sources

Term sources are encoded using the [.source] syntax, and rendered within parentheses after the definition according to the IHO Style Manual.

Example 9. Example on encoding term source (IHO Style Manual 2021)

=== systematic drift rate

That component of drift rate that is correlated with specific operating
conditions.

[.source]
<<IHO-260-1-2004>>

renders as:

systematic drift rate: That component of drift rate that is correlated with specific operating conditions. (IHO Std 260.1-2004)

For terms that are modified or adapted from the source, they are encoded as "adapted from" through an adapted option on the source tag.

Example 10. Example on encoding an adapted term source (IHO Style Manual 2021)

=== drift rate

The slope at a stated time of the smoothed curve of tube voltage drop with time
at constant operating conditions.

[.source%adapted]
<<iso-iec_9945-1>>

rendered as

drift rate: The slope at a stated time of the smoothed curve of tube voltage drop with time at constant operating conditions. (Adapted from ISO/IEC 9945-1:2003)

Annexes

Appendixes are annexes marked as informative instead of normative, which is the default.

Appendixes are numbered with Arabic numerals rather than letters, as a separate sequence from normative Annexes.

[appendix,obligation=normative]
== First Annex

[appendix,obligation=informative]
== First Appendix

renders as

Annex A

First Annex

(This annex forms an integral part of this Recommendation)

Appendix 1

First Appendix

(This appendix does not form an integral part of this Recommendation)

In addition, Annexes can have their own appendixes; this means supplementary clauses to the annex, rather than informative clauses within the annex. Appendices to annexes are marked up with an option attribute of "appendix":

[appendix]
== Annex A
Text

[%appendix]
=== Appendix 1
Text

Blocks

Notes

The footnote on first appearance of a note,

Notes to text, tables, and figures are for information only and do not contain requirements needed to implement the standard.

is automatically generated by Metanorma.

Tables

Table heads and table subheads are marked up as header cells. They are differentiated by line break:

|===
| Header1 | Header2

h| Table Row Head +
Table Row Subhead | Value

Inline

Cross-references

Omission of "clause" at the start of a sentence for cross-references to subclauses is done automatically by Metanorma. If Metanorma’s detection of the start of a sentence is incorrect, you can override Metanorma’s auto-generated text, by providing it explicitly within the cross-reference, e.g. Clause 3.1.

References to the bibliography are automatically populated by designator and bibliographic number (e.g. ISO 639-2, [B1]), if the reference is to a standard or technical report, or otherwise by title and bibliographic number. If you wish to override that, e.g. by using authors instead of title, you should populate the cross-reference text, e.g. Boswell and Johnson [B2].

Footnotes

If a footnote is repeated, Metanorma automatically detects that and converts it into a cross-reference ("See Footnote 1.")

A repeat footnote can be marked up using the footnote macro target (abc in the following example; any identifier can be used), and with the repeat footnote text left blank.

Hello.footnote:abc[This is a footnote]

Repetition.footnote:abc[]

Metadata

Revision history

Revision history is encoded using detailed change history [added in https://github.com/metanorma/metanorma-iho/releases/tag/v0.9.0].

The following information is required:

Date of the document version.
Version of the document.
Description of changes.
Contributor(s) (individual or organization) author responsible for the changes.

The author is expected to be specified with an acronym (or initials, in the case of a person). Relaton requires a proper name to be specified for contributors, but the abbreviation field should be used alongside it.

The following illustrates what semantic markup of IHO document history should look like.

Example 11. IHO revision history

[.preface]
== metanorma-extension

=== document history

[source,yaml]
----
- date:
  - type: published
    value:  2012-04
  edition: 1.0.0
  contributor:
  - organization:
      name: International Hydrographic Organization
      subdivision: Transfer Standard Maintenance and Application Development
      abbreviation: TSMAD
  amend:
    - description: Approved edition of S-102
- date:
  - type: published
    value:  2017-03
  edition: 2.0.0
  contributor:
  - organization:
      name: International Hydrographic Organization
      subdivision: S-102 Project Team
      abbreviation: S-102PT
  amend:
    description: >
      Updated clause 4.0 and 12.0.

      Populated clause 9.0 and Annex B.
    location:
      - clause=4.0
      - clause=12.0
      - clause=9.0
      - annex=B
- date:
  - type: updated
    value:  2017-05
  edition: 2.0.0
  contributor:
  - organization:
      name: International Hydrographic Organization
      subdivision: S-102 Project Team
      abbreviation: S-102PT
  amend:
    description: >
      Modified clause 9.0 based on feedback at S-100WG2 meeting.
    location:
      - clause=9.0
- date:
  - type: updated
    value:  2018-02
  edition: 2.0.0
  contributor:
  - person:
      name:
        completename: Cliff Kottman
        abbreviation: CK
  amend:
    description: >
      Modified clause 9.0. Deleted contents of Annex B in preparation for updated S-100 Part 10C guidance. Added Annex F: S-102 Dataset Size and Production, Annex G: Gridding Example, Annex H: Statement added for Multi-Resolution Gridding, Annex I: Statement for future S-102 Tiling.
    location:
      - clause=9.0
      - annex=B
      - annex=F
      - annex=G
      - annex=H
      - annex=I
----