Question: how to avoid #uuid links and get #tocXX links instead?

[jerstlouis]

What controls whether we get #tocXX instead of #UUID links?

These UUIDs, which change everytime the document is re-generated, are very impractical when we want to link to parts of our huge standard documents, which is the case most of the time e.g., from a repo README listing requirement classes.

I noticed that the ogcna-auto-review documents gets #toc links whereas the /drafts documents get #uuid links

Thanks!

cc @gbuehler

[opoudjis]

Oh dear. This... is not how you're meant to be linking clauses externally. Let me explain what is going on.

• The TOC links such as https://docs.ogc.org/DRAFTS/18-067r4.html#toc20 appear to be legacy links from previous Asciidoctor realisations of documents. Metanorma HTML doesnt have #toc... links like that, and never has: its table of contents is dynamically generated by Javascript, and points to clause IDs. I can't tell you anything about them from Metanorma's side.
• The UUID identifiers are ONLY generated if there is no user-supplied anchor in the identifier. They are generated because there does have to be an identifier for the clause somewhere, and we did not want to trust the built-in Asciidoctor identifier and its ad hoc disambiguation techniques. They are based on a hash of the content of the clause, and are indeed updated whenever that content is updated, by design.
• The way to get invariant IDs for clauses in Metanorma is not to rely on the clause title text, like Asciidoctor natively does (title change), and it is not the default GUIDs we supply. It is by introducing explicit clause anchors in creating these documents to begin with:

[[requirements_overview]]
=== Overview

if you do that, then https://docs.ogc.org/DRAFTS/18-067r4.html#requirements_overview will work, and will remain stable whatever content changes you do.

This is added work on editors, but I honestly don't see an alternative that will persist. If you infer an identifier based on content, it breaks when you update the content. If you infer an identifier based on the title, it breaks when you update the title (or introduce another title that has the same wording). If you infer an identifier based on the hierarchical position of the clause, it breaks when you move the clause, or interpolate clauses before it.

I don't believe this should be a Metanorma matter, but an OGC editorial matter. But explicit anchors on each and every clause of a Metanorma document is what we would regard as good practice, because you never know when you will be called on to cross-reference a clause, either internally or externally—and you can't do so if a known identifier has not been assigned to that clause.

[opoudjis]

• Hidden anchor link surfaced in body of doc next to clause
• Confirm that ToC is pointing to user defined anchors and not making up GUIDs

[ghobona]

Discussed on 2024-04-29

Agreed to add links to each section that has an anchor provided by the editor.

Rule agreed to:

• If editor has provided an anchor, then use the anchor
• else use a GUID

[jerstlouis]

Thanks @opoudjis @ghobona

Right now for Cartographic Styles & Symbology in clause_7_core.adoc we have:

[[rc-core]]
== Requirements Class "Core"

yet in the HTML side bar the link for 8 Core the link is:

https://docs.ogc.org/DRAFTS/18-067r4.html#_25b224b4-e4c3-4556-bc29-63b1171b9b00

(perhaps it's my fault, or it's a separate issue, but right now 5-Conventions is 6-Conventions in the TOC and there is no 5, so numbers are out of sync).

Related to all this, in each requirement we currently define such an anchor:

[[req-core-rules]]
===== Style `stylingRules` property

[requirement]

Currently, these requirements are too deep to show up in the side bar TOC, and the header in the HTML do not contain links. It would be great to have these requirements have anchors that you can easily share (right-click title / Copy link location) to point people to a specific requirement.

Note: even the links that are in the TOC do not contain the link anchor in the HTML, e.g it would be great to have 8. REQUIREMENTS CLASS “CORE” be a link to the document at this current point, as we had in the older ASCIIDoc standard templates.

[opoudjis]

I'll put those links in; I was going to do hover anchor, which is what Asciidoctor does, but I'm open to alternatives.

The ToC GUIDs are a surprise, and I'll try to duplicate. The behaviour you're describing shouldn't be happening, and may be some kind of oversight.

[jerstlouis]

Thanks @opoudjis .

The TOC links such as https://docs.ogc.org/DRAFTS/18-067r4.html#toc20 appear to be legacy links from previous Asciidoctor realisations of documents. Metanorma HTML doesnt have #toc... links like that, and never has:

While it still exists (which may not be for long) see the following anchor that does seem to be generated by metanorma on auto-na-review:

https://opengeospatial.github.io/ogcna-auto-review/21-038.html#toc18

not sure how this is happening, but it is happening on /auto-na-review (and not on /drafts) :)

I'm happy with the anchors explicitly controlled by the editors once the current GUID behavior is fixed, that would be nicer and more persistent than #toc18.

[opoudjis]

Yuck.

In the HTML, clauses are formed as:

<div id="clause-id">
<h1 id="GUID">
....

The ToC is formed by scanning for h1, h2. As a result, it is linking to the GUIDs of the h1, h2, not the well-formed GUIDs of the div containing them, which is the actual desired id.

Yeah, that's an oversight. I do think the real solution is to enable the hover anchor that asciidoctor had natively, and that you are already familiar with in OGC. I'll realise that now, and then go back and see if it is worthwhile changing how the Table of Contents hyperlinks.

[opoudjis]

I'm realising this behaviour globally in Metanorma, because it is desirable behaviour. It is equivalent to enabling both :sectlinks: and :sectanchors: in native Asciidoc.

[ghobona]

@opoudjis Editors rarely provide anchors for every section. They tend to provide anchors for key sections only.

So I presume the system's behaviour would be something like.

• If clause-id of div tag exists, then use it.
• else use GUID of h1 tag automatically generated by metanorma

[opoudjis]

Actually, GUID of div automatically generated. The use of the h1 GUID is an aberration, because I was not thinking anyone would actually use the TOC for anchors...

[opoudjis]

Need to assign distinct CSS class to inline headers (done at the start of paragraphs instead of as separate lines), so that I can detect them and insert anchor links in HTML postprocessing.

[opoudjis]

Need to make TermNum h* consistent with other clauses, enclosing them in div, so that their anchors can be processed consistently.

[opoudjis]

Please find attached a version of 18-067r4.html with anchor highlighting for section titles. Does this meet your needs?

18-067r4.html.zip

[jerstlouis]

@opoudjis Thank you very much, that's a great improvement! :)

(the TOC still have GUID links, but I assume you know that and that just needs a separate fix).

It would also be nice if the requirements themselves would automatically get an anchor highlight as well (e.g., Requirement 1 in the requirement table), which could possibly use an auto-generated anchor based on the requirement id e.g., #/req/core/rules?

The abstract tests e.g., A.1 I think automatically generates a link which currently uses a GUID:

Requirement Requirement 1: /req/core/rules

An automatic anchor for the test table would also be great.

This is because Abstract Tests and Requirements are things that the ETS (and Human Test Suites e.g., me ;)) will always want to point people to (e.g., when a test fail).

[opoudjis]

So:

• I've changed the rendering of headings to insert hover anchor links
• I have made the hover anchor links point to the containing clause ID, which is what the users set in Metanorma, and not the separate ID of the heading itself (which is what most processing of ToC presupposes in HTML)
• I have made the statically generated ToC also point to the destination of those anchor links, the containing clause ID

There's a few new requirements now, and I am separating them out, because I'm not as enthusiastic about all of them:

• Requirements get hover anchor IDs
• Requirements get automatic ID based on the requirement ID, and not a GUID (unless the editor has supplied an explicit anchor)
• Test table gets automatic anchor—by which I think you mean the individual tests in Annex A
• Implicit from the foregoing, automatic ID based on the test ID and not a GUID (unless the editor has supplied an explicit anchor)

I can do hover anchors, and I'll attempt it now, although the tabular rendering may make the sidebar § look ugly.

I am not as enthusiastic about anchors based on the IDs: the IDs will need to remove characters disallowed in XML anchors, so they won't be identical to supplied IDs, and they will be lengthy for anchors. Plus, intervening in that way may be more complicated than I'd like: I'd have to investigate the Modspec-specific code, and get endorsement that OGC is OK with semantically-based automatic hyperlinks for them. @ghobona @gbuehler

So I'd like to separate that aspect to a separate ticket, and defer it.

[jerstlouis]

Thanks a lot @opoudjis !

the IDs will need to remove characters disallowed in XML anchors, so they won't be identical to supplied IDs,

Are forward slashes / allowed? Because requirement identifiers usually only use alphanumeric characters, underscores and slashes.

and they will be lengthy for anchors

I really think this is the single most valuable thing to be able to directly link to a particular requirement, using an anchor corresponding to that requirement ID.

get endorsement that OGC is OK with semantically-based automatic hyperlinks for them

Cool, I hope they like idea, but it sounds very much aligned with what metanorma is trying to do to generate as much as possible from a single source of truth. One less place that editors would need to manually ensure consistency between requirement identifiers and the anchors.

which I think you mean the individual tests in Annex A

That is what I meant, yes.

I can do hover anchors, and I'll attempt it now, although the tabular rendering may make the sidebar § look ugly.

If the § hover anchors is not suitable somewhere (e.g., in the TOC), simply the Section / Requirement X / Test X header text being right click / Copy link -able is just as good. I personally prefer the thing just being right click - Copy link -able without the hover thing but that's just me, and I got used to the § hover.

So I'd like to separate that aspect to a separate ticket, and defer it.

That makes sense, we've gone quite far from my original simple question :)

[ghobona]

@opoudjis I'm happy with the changes implemented and shown in the ZIP file at https://github.com/metanorma/metanorma-ogc/issues/659#issuecomment-2085662728

I agree that the new suggestions should be separated out into new GitHub Issues.

[opoudjis]

This ticket is implemented, so deferring the remainder to the new ticket #663

[opoudjis]

document this functionality