Concept mentions not working in non-Clause 3 of a vocabulary document

[ronaldtse]

From

• Concept mentions not working in non-Clause 3 of a vocabulary document CalConnect/cc-calendar-vocab#3

Errors:

AsciiDoc Input: (ID _dbf283e5-cf07-41c4-9817-aa688d118490): Error: Term reference to `iCalendar` missing: "iCalendar" is not defined in document
AsciiDoc Input: (ID _cf734446-6bbb-429b-9ec7-fdf4f4d08d4c): Error: Term reference to `iCalendar` missing: "iCalendar" is not defined in document
AsciiDoc Input: (ID _c421fa9e-3ef1-402e-8958-d68831912851): Error: Term reference to `vCard` missing: "vCard" is not defined in document

And this also causes metanorma-ietf to crash (metanorma/metanorma-ietf#213).

The way to work with vocabulary documents is documented here:

• https://www.metanorma.org/author/iso/topics/markup/#vocabulary-documents

[heading=terms and definitions]
== Terms related to specific technologies

=== Calendar data formats

==== iCalendar
standard format for representing calendar data

[.source]
<<cc_glossary>>

==== vCalendar
legacy format for calendar data superseded by {{iCalendar}}

[.source]
<<cc_glossary>>

==== vCard
standard format for representing contact information

[.source]
<<cc_glossary>>

==== xCal
XML representation of {{iCalendar}} data

[.source]
<<cc_glossary>>

==== xCard
XML representation of {{vCard}} data

[opoudjis]

Going to CalConnect/cc-calendar-vocab#3

The error is different: the terms are not being recognised as terms at all:

<clause id="_terms_related_to_specific_technologies" obligation="normative">
<title>Terms related to specific technologies</title>
<clause id="_calendar_data_formats" obligation="normative">
<title>Calendar data formats</title>
<clause id="_icalendar" obligation="normative">
<title>iCalendar</title>
<p id="_f659ec5d-98f0-a569-e214-ae67c6afbc49">standard format for representing calendar data</p>

That is because Metanorma has inherited from ISO the constraint that there is only one Terms and Definitions section per document, outside of ISO/IEC vocabulary documents; and 03-22-misc.adoc is marked up as a distinct sister clause to the Terms and Definitions clause, not a subclause of it.

If I comment out that bit:

//[heading=terms and definitions]
//== Terms related to specific technologies

The concepts process fine, because the "Calendar data formats" are recognised as terms fine.

So we have two alternatives:

• In CC, mark "Terms related to specific technologies" up as a subclause of the Terms (include::03-22-misc.adoc[leveloffset=+1]), because CC doesn't know about vocabulary documents, and the Metanorma constraint that there can be only one Terms section per document is good and needs to be preempted in markup
• The Metanorma constraint that there can be only one Terms section per document is only advisory, and if the user puts in a heading attribute wanting there to be two in the document, that should be respected, for any flavour of Metanorma

@ronaldtse Which do you want?

[ronaldtse]

Given that vocabulary documents are quite widespread amongst SDOs, perhaps it is easier if we relax the "one terms section only per document" rule.

For this particular document, I am planning to also cross-publish to ISO as a proper vocabulary document, so I prefer keeping the same structure across documents.

[opoudjis]

Removing the blanket "only one of these clauses per document" restriction if the clause type is specified as a heading attribute.

[opoudjis]

These errors have gone away with the fix to standoc, as the clause is now recognised as a second terms clause.

We now have a different error: isodoc still is expecting to find a single terms section, so the second term section is not getting any anchors processed for it.

[opoudjis]

Explicitly allowing multiple terms & definitions clauses in the isodoc clause_order module