"Overview" section placed at the end of document in S-102

[ronaldtse]

As per:

• iho-ohi/S-102-Product-Specification#108

From @hasel001 :

The largest remaining issue involves (for the PDF) the Overview Section being placed much farther along in the document than where it belongs. See a recent output from a build a few minutes ago as an example.

Do you have any insight as to a solution to get the Overview section to go back to the beginning of the document?

Thanks again. We really appreciate your help.

Sample:

• draftIncluding_03_and_09.pdf

cc: @hasel001 @RohdeBSH

[Intelligent2013]

The issue in the IHO XSLT. It doesn't consider the displayorder attribute in the presentation XML:

    </preface>
    <sections>
        <clause id="_specification_scope" obligation="normative" displayorder="5">
            <title depth="1">3.<tab/>Specification Scope</title>
...
        <clause id="sec-data-product-identification" obligation="normative" displayorder="6">
            <title depth="1">4.<tab/>Data Product Identification</title>
...
...
        <clause id="sec-overview" obligation="normative" displayorder="4">
            <title depth="1">2.<tab/>Overview</title>

[Intelligent2013]

IHO XSLT updated in https://github.com/metanorma/metanorma-iho. Overview clause moved up now:

In the Presentation XML there isn't the clause with number 1.. The clauses start with 2.:

@opoudjis could you check?

[opoudjis]

Will do tonight, this is an issue I have already had to address elsewhere under similar circumstances (Plateau, I believe)

[opoudjis]

Working on this now.

@hasel001 @RohdeBSH Now that I know who you are :) , I'm taking the opportunity to alert you to:

https://github.com/orgs/metanorma/discussions/6

This is where we post update notifications of Metanorma.

Working on this now, next release is going to be 8 July. (It would normally be 1 July, but I'll be out of town that week.) If you're familiar with how to do it, you can retrieve the needed code update from Github; this should be a one-liner.

[opoudjis]

[hasel001]

So, according to the screenshots and the results from our recently built artifacts, the numbering is now correct, in that the first chapter appearing in the document is numbered 1, etc.

However, in document.adoc, the order is as follows:

00-document-history.adoc 01-overview.adoc 02-spec-scope.adoc ... 12-metadata.adoc aa-data-class-enc.adoc

But the order in the rendered document is:

00 Document History 01 Spec Scope ... 11 Metadata 12 Overview AA Data Class Enc

In other words, overview is still at the end (despite its position in document.adoc).

[Intelligent2013]

ping @opoudjis

The Semantic part XML - Overview is first clause in sections:

                    </semantic__preface>
                    <semantic__sections>
                        <semantic__clause id="semantic__sec-overview" obligation="normative">
                            <semantic__title>Overview</semantic__title>
...

The Presentation XML - Overview is last clause in sections:

    <sections>
        <clause id="sec-specification-scope" obligation="normative" displayorder="3">
            <title depth="1">1.<tab/>Specification Scope</title>
...
...
...
        <clause id="sec-overview" obligation="normative" displayorder="14">
            <title depth="1">12.<tab/>Overview</title>
...
        </clause>
</sections>

[ronaldtse]

@opoudjis the Overview clause is always supposed to be Clause 1 in IHO documents.

[opoudjis]

Hm. Easy fix (the ordering of clauses is part of config), but I'm still surprised this has happened.

I'm assuming that Overview is a special clause type, just like Scope, and therefore needs to be identified and put up front. That's a legacy of the ISO model, which always fishes out Scope and puts it up front; if we are to do that, we need to make sure it is done for overviews too. If IHO want a free section ordering model, of just rendering clauses in the order they are entered with no reordering, we can do that too.

[opoudjis]

@opoudjis the Overview clause is always supposed to be Clause 1 in IHO documents.

This is the first I have heard that. And this flavour was implemented four years ago. But then, it was only last month that I was appraised that the "Overview" contains terms, references, and a lot of other content—something that Metanorma did not even allow until ISO 80s formats forced it.

That is a SEVERE problem. If I am not being informed of these requirements, they do not get implemented.

Given what I am seeing as the specification of S-100 11.3 and S-97 A.6.2.1, imposing an ISO style restricted set of fixed-order sections onto IHO is not going to be practical, and I am just going to process clauses in the order they are entered. I'd rather not, but there are too many clause types in those specifications for the rigidity of clause ordering seen in ISO to work well in metanorma-iho.

[opoudjis]

There is a task to impose S-97/S-100 structure, https://github.com/metanorma/metanorma-iho/issues/187, but I am getting rid of the ISO-derived requirement Scope, Normative Refernces, Terms, Other Clauses as top-level clauses, because it is not applicable to IHO with its Overview container. I now think that reordering clauses as we have been doing in Metanorma has been counterproductive anyway, as it is too susceptible to failure.

[opoudjis]

Found the actual bug: do not move the normative ref clause from bibliography to sections in Presentation XML, if it is already in sections. The move is presupposing the old, top level structure of bibliographic clauses, and ends up dumping the entire clause containing the normative references to the end of sections.

[opoudjis]

Fixed:

[hasel001]

@opoudjis @ronaldtse Thank you. I see from the screenshot that it was resolved somewhere. However, when Build runs for the Developing branch of our repo. Please forgive the rather basic question, but what do I need to do to effect those same changes on our repo?

[opoudjis]

Simplest response: wait a week. Metanorma is released every two weeks, and that involves several dozen software libraries being integrated, so the release process is not instantaneous or live; you can monitor the releases on https://github.com/orgs/metanorma/discussions/6 . If you use Docker, you will need to wait longer, the docker releases lag behind.

If you want, you can pull the live code for the various gems live from GitHub—in this case, isodoc and metanorma-iho. If you're not comfortable with doing so, and dealing with potential incompatibilities, I'd just wait till next Tuesday.