Allow cross-referencing of data items

[anermina]

Documents from ISO/IEC 80000 series refer to specific table rows/cells. For example, IEC 80000-6 includes a table of numbered items which are referred to in the text. Currently, we do not support anchors for table rows/cells and can therefore not add proper cross-references.

This is also an issue for the Index section, which originally looks like this:

Note: What can also be noticed from the sample above is that items are also cross-referenced from external sources, which can be encoded using custom localities.

Related to https://github.com/metanorma/iso-iec-80000/issues/1.

[ronaldtse]

Thank you @anermina for raising this. I think these identifiers are actually "item identifiers" where the item identifier pattern is standard-specific.

Technically, this table should be encoded as a YAML file, and we use the item number for referencing.

(I think many of the ISO/IEC 80000 items should be encoded in a YAML format)

[ronaldtse]

@opoudjis isn't this similar to the need of ModSpec where arbitrary identifiers are needed and referenced?

[anermina]

Technically, this table should be encoded as a YAML file, and we use the item number for referencing.

@ronaldtse is it possible to produce the proper cross-references when YAML is used? I only managed to produce the same result as when encoding them in AsciiDoc, so I'd like to double-check whether that is the expected output currently.

[opoudjis]

@opoudjis isn't this similar to the need of ModSpec where arbitrary identifiers are needed and referenced?

I don't see how. The identifiers are still anchored to requirements, and included in requirement markup. This nonsense is pure ad-hoccery, and there is no clear place to tether an identifier to; as you correctly identify, these are novel item identifiers, quite independent of whether they are presented as tables or sonnets.

[ronaldtse]

these are novel item identifiers, quite independent of whether they are presented as tables

Basically I am suggesting a mechanism to define arbitrary data items with assigned identifiers that can be cross-referenced.

Something like this:

[[list-of-items]]
.List of items
item::
identifier::: 6-26.1
name::: magnetic constant, permeability of vacuum
symbol::: stem:[mu_0]
definition::: scalar quantity given by...
remarks::: This quantity...

render_item_table::list-of-items[]

Cross-reference:

<<item:6-26.1>>

[opoudjis]

Basically I am suggesting a mechanism to define arbitrary data items with assigned identifiers that can be cross-referenced.

When exactly does the cavalcade of ad-hoccery in this project end?

So now, you have data that contains identifiers, you have completely made up labels for these identifiers (items? since when?), and you have the non-negligible issue that these items are being rendered as tables by magic, through some mechanism that preserves these item identifiers, that I have no idea about or involvement in. (How did we get from that list of items to the table? XSLT? Lutaml? Where does that list of items live, is it data included in the standard?)

I'm not implementing any of this without a whole lot more concrete thinking than I'm seeing so far.

Oh, and:

<<item:6-26.1>>

No, you do not get to break Asciidoctor syntax or invent yet another ad hoc schema for cross-references. It stops here. There shall be no <<item:. These will be cross-references like any other cross-reference, and they will be handled according to where in the Metanorma XML this data artefact is stored.

[opoudjis]

I reiterate, @ronaldtse, I am not going to implement this without something much more rigorous than what you have said, and my questions remain unanswered.

• Are you proposing a general item definition-list syntax, which shall contain a list of referenceable data items?
• If so, how do we know to render it as a table? Shall there be a fixed rendering option to convert definition lists into tables, provided they have a consistent set of subentries?
• If so, where does the data itself live? Separate to the document, in Metanorma-Extension?

If all of the above is valid, then I can suggest a solution.

(I maintain my objection that this is ongoing adhoccery, that has been making Metanorma bloated and unusable, for years. But that's your decision.)

The list would look like this:

== Metanorma-Extension

[[list1]]
.List of items
item::
identifier::: 6-26.1
name::: magnetic constant, permeability of vacuum
symbol::: stem:[mu_0]
definition::: scalar quantity given by...
remarks::: This quantity...

[[list2]]
.List of items
item::
identifier::: 7-39.1
name::: magnetic constant, permeability of vacuum
symbol::: stem:[mu_0]
definition::: scalar quantity given by...
remarks::: This quantity...

....

== Clause 2

render_item_table:list1[options...]

render_item_list:list2[options...]

Where options can include indexterm (render_item_table:list1[indexterm=name,indexterm_delimiter=","]), to generate an index (boldface vs other index terms, and multiple indexes, are something that is just going to have to wait:

And the expansion of those macros in the main body of the text uses the data stored in metanorma-extension, and is going to look like this:

<table>
<thead>
<tr><th>Identifier</th> <th>Name</th> <th>Symbol</th> <th>Definition</th> <th>Remarks</th></tr>
</thead>
<tbody>
<tr id="item6-26.1>
<td>Item 6-26.1</td>
<td>magnetic constant, permeability of vacuum 
<index><primary>magnetic constant</primary></index>
<index><primary>permeability of vacuum</primary></index>
</td>
<td>stem:[mu_0]</td>
<td>scalar quantity given by...</td>
<td>This quantity...</td>
</tr>
</tbody>
</table>

In addition, we may end up having to define the "Item" label per document rather than per flavour, if I can't have an assurance that "item" will be used consistently.

I can do this, but I'm not going to do it if the next document that turns up means I have to discard this solution. I expect this to be a reusable solution, and I expect someone to do the analysis of standards documents and confirm that this solution can be reused. Not actioning until then.

[opoudjis]

From: https://github.com/metanorma/iso-iec-80000/issues/49

I remain unhappy.

For example, I just said in https://github.com/metanorma/metanorma-standoc/issues/762

I can do this, but I'm not going to do it if the next document that turns up means I have to discard this solution. I expect this to be a reusable solution, and I expect someone to do the analysis of standards documents and confirm that this solution can be reused. Not actioning until then.

I look at this ticket, and that ticket.

That ticket has:

Item number: 6.26-1

This ticket has:

Item number: 13-1

What the HELL is that (801) following it?! It is NOT part of the item number, since it is not used in cross-referencing ("item 13-1").

If it is a distinct field, a simple translation of a definition list to a list is not going to concatenate two random fields into the one cell: that is a job for Lutaml, not for a Metanorma macro. (And I have just had implemented the mechanism to make Lutaml able to look up YAML content in metanorma-extension.)

I have proposed a solution for one document, and the very next document, it falls over.

Therefore:

• It is much too premature for any solution to be implemented, until someone has gone through and worked out all the formatting requirements for inline rendering of data. This is not the last time a horrible surprise is going to turn up.
• I had proposed mapping definition lists to tables in the previous ticket, but it already looks to me like the only solution able to deal with the likely complexity of data here is Lutaml.

So the table would end up something like:

[lutaml-something,#list1]
|===
| Item | Name | Symbol | Definition | Remarks

{% for item in lutaml-something %}
{% capture indexterms %}
{{ item.name | split: ", " }} // array of index terms, splitting "name" on comma
{% endcapture %}
{% 
| Item {{ item.identifier}}  
_{{item.otherlabel}}_  // concatenate otherlabel to the identifier, in italics 
[[_item_{{item.identifier}}]]  // provide an anchor for crossreferences
| {{item.name}} 
{% for indexterm in indexterms %}
(( indexterm )) // we have enabled each of the comma-delimited strings in the name to be indexed
{% endfor %}
| {{item.symbol}} 
| {{item.definition}} 
| {{item.remarks}} 
{%endfor%}