Broken link to formula

[opoudjis]

From https://github.com/metanorma/annotated-express/issues/137

First, in Part 42:

The surface Euler equation [(7)](https://github.com/metanorma/annotated-express/issues/document.1.xml.6.html#eqn7_iso10303-42_iso10303-42_5_Topology_schema) applies with _ B _ = 0,

The hyperlink from (7) works, but is pointing to equation (259). Equations are numbered sequentially within the document, and that means that the numbering within each schema for equations must be ignored. @HassanAkbar if you are rendering the Express as <<eqnWhatever,(7)>>, don't, just make it <<eqnWhatever>>. You must not assume that the source document equation numbering will survive inclusion in an ISO document.

Second, there is a broken link:

With the (temporary) removal of boldface and italics, there is now only 1 link broken in the collection of parts 41 through 45:

An <b>open_path</b> is a graph for which M = 1 and _ <b>G</b><sup>p</sup>_ = 0, so the Euler equation <a href="6_schema.xml#eqnGM1">(1)</a> reduces in this case to

Notice the undigested, unprocessed italics marks, _.

This tells me that cross-references to equations are potentially broken, @HassanAkbar

Let's see where this is:

Part 42, 5.4.18

The Express original is https://github.com/metanorma/iso-10303-stepmod-wg12/blob/85ac47124a35fb985b99d0148e9bbe16609cb197/data/resources/topology_schema/descriptions.xml#L514

<p> A <b>open_path</b> is a type of
    <express_ref linkend="topology_schema:ir_express:topology_schema.path"/>,  such that a
    traversal of the path visits each of its vertices exactly once. In
    particular, the start vertex and end vertex are different.
    An <b>open_path</b> is a graph for which M = 1 and <i><b>G</b><sup>p</sup></i> = 0, so the Euler
    equation (1) reduces in this case to</p>
   <eqn>     (<b><i>V</i></b> - <b><i>E</i></b>) - 1 = 0  &#8195;  &#8195;<A name="eqn3"> (3) </A></eqn>

I don't know @TRThurman @HassanAkbar how that (1) is being turned into a cross-reference, but a formula with id eqnGM1 is defined in the same document (somewhere), so the Asciidoc crossreference should be... well, I don't know what it should be, but presumably <<eqnGM1>>. Wherever 6_schema.xml is coming from, Metanorma does not know about it.

[opoudjis]

For updates on this, see https://github.com/metanorma/annotated-express/issues/137

@TRThurman please provide further updates on that issue to this ticket

@HassanAkbar from what I am seeing there, the broken link is a source markup issue, and I don't think you can do anything about it right now, since the markup is apparently faked. Hold off on doing any work on it.

[opoudjis]

OTOH @HassanAkbar the issue with allowing formula autonumbering, and not providing the equation numbering in the crossreferences yourself, is still valid.

[TRThurman]

Did some archeology yesterday. As near as I can tell, this is just some garbage inserted into the source to make a dummy link. 6_schema.xml is a 'seed' xml file that causes a page-oriented xslt file to be executed so a section of a document can be rendered using the publication xslt chain to generate only that section. 6_schema.xml corresponds to clause 6 (surprise) in part 42. As noted elsewhere I have notified the part owner who is no longer a happy camper (well to be honest he signed up for it, knowing there were issues with content, but not with markup.)

Also discovered that there are two controlling dtds for the xml. One provides for eqn.id, the other does not. And there is no dtd that defines eqn_ref anyway, so it is a hot mess. The only cross reference supported in STEPmod is for EXPRESS constructs.

[TRThurman]

Just noticed that @opoudjis requested we post new comments to this issue. mea culpa.

[TRThurman]

@ronaldtse, Can we assume that notes, examples, figures tables, equations will all be auto-numbered? With a side effect that they all have ids so they can be persistently referenced(at least in the document context)?

[TRThurman]

OTOH @HassanAkbar the issue with allowing formula autonumbering, and not providing the equation numbering in the crossreferences yourself, is still valid.

@opoudjis, What is the difference between a formula and an equation?

[opoudjis]

@ronaldtse, Can we assume that notes, examples, figures tables, equations will all be auto-numbered? With a side effect that they all have ids so they can be persistently referenced(at least in the document context)?

Yes. Of course, if you persistently identify a table and cross-reference it, you need to supply that identifier in the source, and I don't know whether you do. But for formulas, it ends up looking in Asciidoctor like

[[formula-identifier-1]]
[stem]
++++
formula
++++

...

<<formula-identifier-1>>

And <<formula-identifier-1>> will be automatically replaced by the incremental number of the formula in the Presentation XML. (The difference between Semantic and Presentation XML is that the latter resolves labelling/internationalisation and autonumbering, as well as simplifying some of the rendering.)

And as I said in the start of this ticket, we are already doing that for formulas, so you do have persistent formula links already. We just need to remove your per-schema numbering, and allow Metanorma to supply its own autonumbering, following ISO style.

What is the difference between a formula and an equation?

Right now none, although there is a ticket to differentiate them in train. They will be numbered in the same sequence, unless we program otherwise.

[opoudjis]

What is the difference between a formula and an equation?

Right now none, although there is a ticket to differentiate them in train.

That's just been done, although it only matters for ISO TBX: https://github.com/metanorma/metanorma-standoc/issues/686 . The rendering is identical, I was just being loose in my vocabulary.

[HassanAkbar]

@opoudjis I've updated the stepmod-utils to change the following

• <a href="#eqn7">(7)</a> was being converted to <<eqn7,(7)>> will now become <<eqn7>>
• <a href="6_schema.xml#eqnGM1">(1)</a> was being converted to link:6_schema.xml#eqnGM1[(1)] will now become link:6_schema.xml#eqnGM1

Is this correct? and is there anything else that needs to be done related to links?

Update

• <module_ref linkend="assembly_module_design:4_entities:figure:pudv">Figure 1</module_ref> was being converted to <<figure-assembly_module_design-pudv,Figure 1>>, will now become <<figure-assembly_module_design-pudv>>
• <module_ref linkend="independent_property_definition:4_entities:table:T1">Table 1</module_ref> was being converted to <<table-independent_property_definition-T1,Table 1>>, will now become <<table-independent_property_definition-T1>>

[opoudjis]

I am ok with these changes, but @ronaldtse and I have had a disagreement on when and where such issues should be addressed, given the business context. So the call on these has to be his.

[ronaldtse]

The changes are fine but I want to make sure that if the link has an external prefix of “Figure” it would also be replaced.

[HassanAkbar]

The changes are fine but I want to make sure that if the link has an external prefix of “Figure” it would also be replaced.

@ronaldtse I didn't understand what you mean by external prefix of “Figure” Can you point me to where I can read about it or give an example?

[opoudjis]

He means a cross-reference like <<blahblahblah,Figure (8)>>. "Figure (8)", too, should be replaced by just the anchor, since Metanorma knows to label figures, tables, notes with the right label.

[ronaldtse]

Not only that, but this Figure <<blahblahblah,(8)>>.

[HassanAkbar]

@ronaldtse @opoudjis So basically anything of the form <<blahblahblah, anything>> will get converted to <<blahblahblah>>.

[opoudjis]

Νο. <<figure,this figure>> would not be converted. Only something with a number, and an optional label before it like "figure".

[opoudjis]

Well, it's still there, though the section is now 5.5.19, and the equation (with more sections being recognised as the template has been debugged) is now (272)...

[ronaldtse]

@HassanAkbar is this issue already addressed? Thanks.

[HassanAkbar]

The changes for this were made in the linked PR here -> https://github.com/metanorma/stepmod-utils/pull/228

@opoudjis can you confirm if this is complete? or do we need to do something else in this ticket?

[ronaldtse]

Closing.