Cross-reference styles

[Intelligent2013]

Source issue: https://github.com/metanorma/metanorma-iso/issues/1134#issuecomment-2010589203

Issue 1

Some ISO original documents have Clause prefix before 2nd level annex sub-clause. For example, https://github.com/metanorma/mn-samples-iso-private/blob/main/reference-docs/19152-1_2024.pdf.

• reference from Annex A sub-clause to another sub-clause
  • rendered PDF:
  • production PDF:

Another PDF (https://github.com/metanorma/iso-6709/blob/main/reference-docs/ISO%206709%20ed.3%20-%20id.75147%20Publication%20PDF%20(en).pdf) doesn't have the prefix Clause:

In https://www.iso.org/sites/directives/current/part2/index.xhtml#_idTextAnchor321 there is the example with 'Clause', but not strict requirement:

I.e. there isn't a common approach.

From https://www.metanorma.org/author/iso/topics/markup/#cross-references:

ISO clause references will suppress the word "Clause" before a subclause reference

But in https://www.metanorma.org/author/topics/document-format/xrefs/#xref-styles:

@opoudjis is there a way to change the current behavior ( suppress the word "Clause") and apply the default style short? I.e. if I set <<anchor,style=short%>> explicitly, then the word "Clause" is showing.

Issue 2

Sometimes, the prefix 'Subclause' is using:

• reference from Annex A sub-clause to main section sub-clause
  • rendered PDF
  • production PDF

And in another section, without prefix:

Even in https://www.iso.org/sites/directives/current/part2/index.xhtml#_idTextAnchor218 the Subclause is using one time:

@ronaldtse do we need to support the user-defined prefix? For example: <<clause4_2,prefix=Subclause%>>.

[opoudjis]

I will respond tonight, but I am not particularly motivated to perpetuate ISO editorial incompetence and vagueness. I regard the inconsistent use of Clause, Subclause, and Nothing as a bug, not a feature, let alone as something we should be supporting. I will see if the structure will allow overrides...

[opoudjis]

Issue 1: You misunderstand the point of <<anchor,style=short%>>. style=short contrasts with basic, full, or id: using the title, the title + the clause number, or a URI for the cross-reference. It has absolutely nothing to do with whether "clause" is used or not used in the cross-refererence, it is about the use of the number, and the use or non-use of the prefix is bound by different rules. <<anchor,style=short%>> will not be the mechanism to realise what you are asking for.

Issue 1 being an instance of ISO editorial inconsistency, it deserves no better than to be considered in the same breath as Issue 2. Rather than indulge muddleheadedness, by making the use of "Clause" optional depending on what the author had for lunch the previous day (B.2 vs Clause B.2? The hell?!), we will have the same rule we have now, a rule which comes from the historical source of ISO rendering, BSI. I'm certainly not going to write custom code in BSI to realise a rule that should be inherited from ISO in our scheme.

Instead, I will treat "subclause" and "clause" before subclauses in the same way: as an idiosyncratic custom prefix.

We can implement this, with a user-defined label prefixed to the cross-reference, instead of what Metanorma wants to use (including nothing, as in this case). So <<anchor,label=Clause%>> or <<anchor,label=Subclause%>>. The label would be used instead of anchor[:elem] to populate anchor[:xref], which defaults to "#{anchor[:elem]} #{anchor[:value]}". (anchor[:value] is the number; so "Subclause 3" instead of "3", "Clause 3.2.1" instead of "3.2.1".) This would be overridden in anchor_xref() in Presentation XML.

We can implement this. I do not want to implement this. I think this is perpetuating editorial laxity, and is compromising what Metanorma is for. The fact that ISO in 2024 is starting to make up prefixes like "Subclause" is indefensible.

[opoudjis]

I'm implementing this under protest. There are circumstances under which you would want this, they are just bad ones, and the fact that it's a distinct attribute will at least make that obvious.

[opoudjis]

I'm implementing this, but I am once again protesting, @Intelligent2013 @ronaldtse, that this constant accumulation of little edge cases over the past five years—to satisfy self-indulgence on the part of SDOs who only understand the flexibility of Word documents, and do not understand their own editorial rules—is continuing to make Metanorma unmanageable.

By requesting a fifth user parameter on cross-references, you are contributing to making Metanorma less learnable and less maintainable. And that is because the answer to SDOs—particularly SDOs who are not committed to using our product to begin with—is almost never "no" from us. The response to a 2024 document including "subclause" should not be "let's allow a means of entering it", it should be "we will not encode your mistakes."

It isn't, because there is no plan here. There's just been five years of shiny objects. With supporting 1954 format PDF rendering (!!!) the latest.

[opoudjis]

Going to rationalise the extracting of % parameters from anchors, it cannot rely on fixed order any more.

[Intelligent2013]

@opoudjis thanks!