search

opengeospatial / CoverageJSON

Public repo for CoverageJSON project
Apache License 2.0
11 stars 8 forks source link

Stable anchor links for all specification sections #127

Closed letmaik closed 1 year ago

letmaik commented 2 years ago

Currently, it's not possible link to specific sections of the spec in a stable way. E.g. https://opengeospatial.github.io/ogcna-auto-review/21-069.html#toc20 links to the Parameter objects section but this is not stable.

@ghobona Is there a way to manually define anchor names for each section?

ghobona commented 2 years ago

Yes, you can place [[example_anchor]] on a line above the section header.

Once you have done that, you can then link to the section using https://opengeospatial.github.io/ogcna-auto-review/21-069.html#example_anchor

Screenshot 2022-09-05 at 08 53 35
chris-little commented 2 years ago

@jonblower agreed to add stable anchors at relevant parts of the spec. this includes each of the top level clauses, and lower levels within the detailed spec in clause 10.

jonblower commented 2 years ago

@ghobona can you help me with a couple of questions about this please?

  1. Should we use [[anchor_text]] or [#anchor_text] syntax? The docs I've found online suggest that the latter is preferred, but your example above uses the former.
  2. What is the meaning of things like [keywords] and [source] (see clause_0_front_material.adoc), i.e. with single square brackets? Are these anchors too, and f not, should we add anchors to these sections?
chris-little commented 1 year ago

@jonblower @letmaik PR#137 adds plenty of stable anchors throughout the document. Are there any more that you would like? @ghobona Please confirm or correct the front matter - I may have overridden some metanorma tags (I replaced some single bracket phrases with double bracket phrases rather than adding. E.g. Clause 0, Abstract.

jonblower commented 1 year ago

Looks good to me!

chris-little commented 1 year ago

@letmaik Could you test some anchors please after tonights build? Are there enough anchors? If you are happy, we can close this issue.

letmaik commented 1 year ago

I don't see any change in the anchors.

letmaik commented 1 year ago

Ok, so, the new anchors do work, for example #parameter_objects, but they are not discoverable. The TOC still uses the auto-generated ones.

chris-little commented 1 year ago

Anchors issue closed as agreed at Task Team 2022-11-30. New issue will be raised for discoverability of internals of OGC specs.