Metanorma: Aequitate Verum

Typical sections in IHO

General

The easiest way to ensure that you are following the document structure that IHO 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 IHO document contains the following content order:

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

Terms and definitions

The terms and definitions is used to define important terms and cite them throughout the standard.

References

The references section contains normative references, it is considered a “bibliography” section.

Note
In IHO there are two “bibliography” sections. The “References” section for normative references, and the “Bibliography” section which is for informative references.

Content sections

After the sections above, any number of content sections can be added.

Annex sections

General

Annex sections are declared by prepending the [appendix] tag above the section declaration. 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: [appendix,obligation=normative]

Example 2. Example of creating a normative versus an information annex
// 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.

Glossary

IHO documents support an extra definitions section that represents informative terms, as a "Glossary" section in the annex.

It can be encoded as follows:

Example 3. Example of creating the Glossary section
[appendix]
== Glossary

=== My term

My definition
...

The usage and syntax of this section is identical to that of Terms and definitions. Please refer to the terms and definitions syntax on how to write out the terms in the Glossary.