Consistent treatment of IHO Revision/Document history

[ronaldtse]

From @anermina on S5:

Revision history is placed among annexes in the generated document, while it's placed in the preface in the original. I didn't change this order yet. Please let me know whether IHO documents should include Revision/Document history section in preface.

We need to confirm how document revision/history is handled inside a document.

Originally posted by @ronaldtse in https://github.com/metanorma/mn-samples-iho/pull/40#issuecomment-632449138

[ronaldtse]

Asked IHO for clarification:

Some documents contain the document revision history, e.g. S-5/S-8 Guidelines, S-102.

The formats aren’t entirely consistent (as attached).

The necessary elements seem to be:

• Date
• Edition/Version (also relevant to the other emailed question)
• description of changes
• author (if available)

Can we settle on a consistent format, such as:

—————————————————————————— | Date | Version (edition) | Authorship | Description | ——————————————————————————

[ronaldtse]

S-5/S-8 Guidelines:

S-102:

This is also aligned with NIST and OGC document history.

[opoudjis]

Following the work done in the BSI ticket, this is going to be the document history encoding for the samples given:

[.preface]
== misc-container

=== document history

[source,yaml]
----
- date:
  - type: published
    value:  2017-03
  edition: 2.0.0
  amend:
    - description: Covers both S-5 and S-8
- date:
  - type: published
    value:  2016-07
  edition: 1.1.0
  amend:
    - description: General editing and formatting
    - description: Section 3.2 on time frames modified
      location: clause=3.2
    - description: Modification of section 8.2. Define eligible submission, split review process between individual evaliation and IBSC review process
      location: clause=8.2
    - description: Inserted checklist and flow diagrams to Annex A
      location: annex=A
- date:
  - type: published
    value:  2016-01
  edition: 1.0.0
  amend:
    description: First edition
----

and

[.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:
        - organization:
            name: International Hydrographic Organization
            subdivision: S-102 Project Team
            abbreviation: S-102PT
        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
      - date:
        - type: updated
          value:  2018-06
        edition: 2.0.0
        contributor:
        - organization:
            name: International Hydrographic Organization
            subdivision: S-102 Project Team
            abbreviation: S-102PT
        amend:
          description: >
            Modifications to align with S-100 v4.0.0, S-100 Part 10c development, and actions from 4th April S-102 Project Team Meeting.

            Modified content throughout the following sections:

            * Clause 1, 3, 4, 5, 6, 9, 10, 11, and 12.
            * Annexes A, B, D, F, G, and I.
          location:
            - clause=1
            - clause=3
            - clause=4
            - clause=5
            - clause=6
            - clause=9
            - clause=10
            - clause=11
            - clause=12
            - annex=A
            - annex=B
            - annex=D
            - annex=F
            - annex=G
            - annex=I
----

[opoudjis]

At this time, absent any guidance, I am inserting "Document history" as the final preface section if machine readable document history is supplied.

[opoudjis]

Implementation is now waiting on https://github.com/relaton/relaton-bib/issues/82