PDF/Word: ISO EPM feedback ISO/DIS 10303-2: Move the subheadings on the same line as the subclause number

[ronaldtse]

Move the subheadings on the same line as the subclause number, e.g. 3.1.2 Fundamentals of product description and support.

[Intelligent2013]

@ronaldtse could you point to the document source? Thanks.

[opoudjis]

@Intelligent2013 A word of caution here, before you fix anything, @Intelligent2013

In ISO, term numbers appear separate to terms:

---

3.4
parboiled rice
rice whose starch has been fully gelatinized by soaking paddy (3.1) rice or husked rice (3.2) in water
followed by a heat treatment and a drying process

---

Whereas normal subclause numbers appear in the same clause as the title:

---

6.1 Moisture content

---

if the subheading and the subheading number in 3.1.2 appear on separate lines, that is because 3.1.2 is being processed as a term, whereas it is intended as a normal subclause within a terms section (as the title itself makes clear: "3.1.2 Fundamentals of product description and support".)

That means that this clause needs to be tagged with [.nonterm] in stepmod2mn, following https://www.metanorma.org/author/topics/document-format/section-terms/#subclauses . This needs to be fixed in the source Asciidoctor, not in the PDF rendering.

However, clearly the processor needs to know when a subclause of a terms clause is a normal subclause, and when it is a term. Hopefully that distinction can be made based on the source XML...

[Intelligent2013]

Currently, stepmod2mn puts [.nonterm] already, like this:

[[defns]]
== Terms, definitions and abbreviated terms

[[sec_3.1.1]]
[.nonterm]
=== Terms defined in ISO 8601

PDF renders:

except one place:

[[sec_3.1.4]]
=== Other terms and definitions

PDF renders wrongly:

I'll fix it.

But regarding the original issue

e.g. 3.1.2 Fundamentals of product description and support.

I didn't find this document yet with the header Fundamentals of product description and support.

[Intelligent2013]

Hmm, I've added [.nonterm] before === Other terms and definitions:

[[sec_3.1.4]]
[.nonterm]
=== Other terms and definitions

For the purposes of this document, the following terms and definitions apply:

[[sec_3.1.4.1]]
==== [[term-agreement_of_common_understanding]]agreement of common understanding

result of discussions between the partners of product data exchange or sharing that ensures that all of them have the same understanding of the transferred or shared information

and now the sub-clauses are not recognized as terms:

as expected regarding documentation (https://www.metanorma.org/author/topics/document-format/section-terms/#subclauses):

The [.nonterm] attribute must only be used in subclauses that do not contain any terms underneath (like the example above). > Otherwise, these terms will not be processed following the corresponding formatting rules.

Without [.nonterm] before === Other terms and definitions:

@opoudjis how to treats === Other terms and definitions as clause header, non term?

[opoudjis]

I hate Metanorma.

Any clause within a “Terms and definitions” section which is a non-terminal subclause (has child nodes) is automatically considered a terms (or definitions) section.

On the other hand, any descendant of a nonterm clause is also a nonterm clause.

... except if this is an ISO document, in which terms can have subterms.

That's something we're treating as an ISO-specific exception, https://www.metanorma.org/author/iso/topics/markup/#systematic-order , and we deal with it by not putting [.term]

So:

== Terms and definitions

=== Grouping

==== Term 1

[.term]
=== Grouping

==== Term 2

[.nonterm]
=== Grouping

==== Term 3

converts to:

<terms id="_terms_and_definitions" obligation="normative">
<title>Terms and definitions</title>
<p id="_c9f2bca4-755b-d520-4086-e4b46a3a0909">ISO and IEC maintain terminology databases ....:</p>


<terms id="_grouping" obligation="normative">
<title>Grouping</title>
<term id="term-Term-1"><preferred><expression>
<name>Term 1</name>
</expression>
</preferred>
 </term>
</terms>

<term id="term-Grouping"><preferred><expression>
<name>Grouping</name>
</expression>
</preferred>
<term id="term-Term-2"><preferred><expression>
<name>Term 2</name>
</expression>
</preferred>
 </term>
 </term>

<clause id="_grouping_3" inline-header="false" obligation="normative">
<title>Grouping</title>
<clause id="_term_3" inline-header="false" obligation="normative">
<title>Term 3</title>
</clause>
</clause>
</terms>

and renders as:

But that means that leaving out [.nonterm], as it originally was, should be rendering correctly. So I don't understand what is happening. Compiling myself...

[opoudjis]

Replicated behaviour: it's being processed as term/term, not terms/term. Investigating why.

[opoudjis]

Got it.

Headings that are groupings of terms are not meant to have any text. If they do have text, that text is considered to be a term definition.

The text "For the purposes of this document, the following terms and definitions apply:" is not a term definition, it is the kind of initial terms boilerplate text we elsewhere signal explicitly as the same kind of text, per https://www.metanorma.org/author/topics/document-format/section-terms/#overriding-predefined-text

So this will work:

[[sec_3.1.4]]
=== Other terms and definitions

[.boilerplate]
==== {blank}
For the purposes of this document, the following terms and definitions apply:

[[sec_3.1.4.1]]
==== [[term-agreement_of_common_understanding]]agreement of common understanding

result of discussions between the partners of product data exchange or sharing that ensures that all of them have the same understanding of the transferred or shared information

[NOTE]
--
The agreement may be formalized in a document.
--

Yes, it's subtle, but I'm not the one introducing this bizarre profusion of mixed up terms and clauses. Adding to documentation.

[Intelligent2013]

@opoudjis I've just added

[.boilerplate]
==== {blank}

before

For the purposes of this document, the following terms and definitions apply:

and in the XML, the header is 3.4 Terms and definitions instead of 3.4 Other terms and definitions.
Left - updated adoc, right - original adoc.

And there is another side-effect - the boilerplate

For the purposes of this document, the following terms and definitions apply.
ISO and IEC maintain terminology databases for use in standardization at the following addresses:
ISO Online browsing platform: available at...

is missing in the new XML:
Left - updated adoc, right - original adoc.

[opoudjis]

I hate my life.

OK, leave this with me. This is going to result in code changes, it's something I clearly had not anticipated.

[opoudjis]

The automated naming of sections is looking at

== Terms, definitions and abbreviations

[.nonterm]
=== Terms in X

[.nonterm]
=== Terms in X

=== Other Terms

=== Abbreviations

And it is deciding that, since "Other Terms" contains terms, and no abbreviations, it is the first node to be called "Terms & Abbreviations." And it would be, but for the fact that there are other collections of terms nearby (some of which are clauses and not terms).

What is actually happening is that, once there are hierarchical collections of terms, so any nodes not covered by "terms & definitions", "abbreviated terms", etc, we cannot be automatically naming nodes.

[opoudjis]

Fixed the auto-titling, preventing it from happening. But boilerplate is still not being inserted.

[opoudjis]

Boilerplate placement hitherto has assumed a well-ordered terms section; it is placed in the earliest of a terms clause, or a clause with terms but no symbols:

• Terms

  • BOILERPLATE
  • Term 1

• Terms & symbols

  • Terms
    • BOILERPLATE
    • Term 1
  • Symbols

But this has not anticipated cases like here, where there are random clauses, not containing terms though describing them:

• Terms & symbols

  • (B)
  • Clause describing Terms 1
  • Clause describing Terms 2
  • Other Terms
    • (A)
    • Term 1
  • Symbols

• Terms & symbols

  • (B)
  • Terms 1
    • (A)
  • Terms 2
  • Terms 3
  • Symbols

Currently the boilerplate is going to Other Terms, because it is the first node containing terms and not containing symbols. But if there are multiple terms collections, or clauses before the one term collection, that guess is wrong: the boilerplate has to go under the topmost node, so it is not specific to one terms collection instead of another: not (A) in the examples above, but (B).

[opoudjis]

ISO/IEC DIR 2 refers vaguely to introductory text of Clause 3: https://www.iso.org/sites/directives/current/part2/index.xhtml#_idTextAnchor208

But in the case of Terms Definitions & Symbols, the introductory text does not go to the start of Clause 3, but to the start of Terms. And I am now having to deal with a test case in ISO, which says that the introductory text does go in the first of multiple terms collections.

ISO have been, once again, negligent in specifying precisely what the expected formatting is, and I have already spent many hours trying to get this right.