1.1: HTML should use meaningful anchors

VladimirAlexiev commented 7 months ago

The anchor for eg section Table D.1 — Alignment: GeoSPARQL SHACL Shapes uses a GUID: https://docs.ogc.org/is/22-047r1/22-047r1.html#_4d33c3fd-4f99-4151-bdf1-bfae3736062c

It's much better if anchors are meaningful and reproducible, like README sections on github and anchors in w3c specs. Otherwise the ability to cite a specific version (a major advantage of HTML compared to PDF) is lessened.

VladimirAlexiev commented 7 months ago

Not all anchors use GUIDs. Eg "10.7.4. Property: geo:hasSpatialResolution" uses this anchor: https://docs.ogc.org/is/22-047r1/22-047r1.html#10-7-4-%C2%A0-property-geo-hasspatialresolution This is better, but it has 2 parasitic Unicode chars %C2%A0, please sanitize them.

Also, it would be great to add a "paragraph" char at every heading to allow the user to copy the direct link (including anchor).

VladimirAlexiev commented 7 months ago

Inspection shows that the story is more complicated:

<div id="_table_of_shacl_shapes">
<h2 id="_4d33c3fd-4f99-4151-bdf1-bfae3736062c">
<a class="anchorjs-link " aria-label="Anchor" data-anchorjs-icon="" href="#_4d33c3fd-4f99-4151-bdf1-bfae3736062c" style="font-style: normal; font-variant: normal; font-kerning: auto; font-optical-sizing: auto; font-feature-settings: normal; font-variation-settings: normal; font-weight: normal; font-stretch: normal; font-size: 1em; line-height: inherit; font-family: anchorjs-icons; position: absolute; margin-left: -1em; padding-right: 0.5em;">
</a>
D.3.&nbsp; Table of SHACL Shapes</h2>

So there are two anchors at that position: the bad one (h2.id) is used in the TOC
There is an attempt to show a "paragraph icon" with data-anchorjs-icon, but it doesn't show for me
Perhaps the reason is that <a class="anchorjs-link "></a> closes before the heading text, or because there's a trailing space in the class name?

VladimirAlexiev commented 6 months ago

As @situx pointed out in #507, the official doc https://docs.ogc.org/is/22-047r1/22-047r1.html behaves differently from the github.io builds. Those have meaningful anchors (eg https://opengeospatial.github.io/ogc-geosparql/geosparql11/spec.html#_d_1_tools) and the paragraph mark works:

cc @ghobona, @ogcscotts

opengeospatial / ogc-geosparql

1.1: HTML should use meaningful anchors #506