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.
[.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:
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.
[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. |
=== 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.
=== 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. |
=== 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.
=== 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.
=== 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.
See also
=== acceleration-insensitive drift rate
related:seealso[drift rate]
related:seealso[systematic drift rate]
The component of systematic drift rate that has no correlation with acceleration.
renders as:
acceleration-insensitive drift rate: The component of systematic drift rate that has no correlation with acceleration. See also: drift rate; systematic drift rate.
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.
=== 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.
=== 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
tag::tables-iho[]
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
end::tables-iho[]
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
Semantic markup of document history can be added to the document, using Metanorma extension and Relaton YAML [added in https://github.com/metanorma/metanorma-iho/releases/tag/v0.9.0]. The following information is required:
-
The date of the document version.
-
The version of the document.
-
Description of changes.
-
The (personal or corporate) 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:
[.preface]
== Misc container
=== 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
----