search

w3c / web-annotation

Web Annotation Working Group repository, see README for links to specs
https://w3c.github.io/web-annotation/
Other
142 stars 30 forks source link

Outdated anchor numbering in TR html page #427

Open gsergiu opened 7 years ago

gsergiu commented 7 years ago

It seems that the naming of anchors is not synchronized with the name/numbering of the examples. It would be usefull to keep them in sync see: https://www.w3.org/TR/annotation-model/#example-1

azaroth42 commented 7 years ago

This is an issue with respec.

As you can see here: https://github.com/w3c/web-annotation/blob/gh-pages/model/wd2/index-nametemplate.html#L373

We don't manually name the anchors at all.

azaroth42 commented 7 years ago

In other words, while I agree this would be useful, I do not believe it qualifies as "Errata" and proposed to remove ErratumRaised, and instead treat as guidance for future specification management. Please give :-1: on the issue not this comment if you agree this is not Errata, or :+1: if you think this should be recorded as Errata.

gsergiu commented 7 years ago

well.. I'm not familiar with the mechanism used to generate the anchors, but there are definitely some inconsistencies within the specifications document on their usage.

  1. Another incosistency is found in section 1.2 where the Examples 1 and 2 are referenced, but the anchors of the sections are used (instead of direct example anchors), sections 3.1 and 3.2.1.

  2. If I was cracking the numering logic of respect correctly. It seems that it starts with example(-0) and increments the anchor number each time a new <h4>Example</h4> element is found in the specifications. It would pe a smaller problem if the difference between the example number and the anchor number would be predictable, but it seems that the Example 7 has no anchor assigned. (#example-5 -> Example 6, and #example-6 -> Example 8). The same happens with the Example 9, Example 27, Example 35, Example 40. By looking in the source code I think that the missing <h4>Example</h4> are probably the cause of these inconsistent behaviour.

The thing identified at point 1. is probably something we would like to correct for V1. The anchor numbering described in 2., is probably a nice to have, it doesn't really affect the understanding of the text (only its re-usability/user experience) . I hope it can be solved by added the missing headings, without the need to indicate them in the errata.

gsergiu commented 7 years ago

If my supposition is correct, probably an issues can be open for respec, to indicate that the generation of the example text (i.e. Example X) is likely to be based on the class evlement, while the generation of anchors is likely to happen basing on the heading element (i.e. <h4>Example</h4>) The anchor numbering and the numbering in naming could also by synchronized (e.g. #example-x to point to Example x).

azaroth42 commented 7 years ago

Yes, but we can't change the documents and issuing an actual erratum to say that something invisible could change to make things better is just wasting people's time. Hence, postpone to when we can actually make changes.

gsergiu commented 7 years ago

I'm not very familiar with the process, it is ok for me to postpone. I just wanted to analize the root of the problem.. and the possible solution.