Re-encode all SpecificationHeadings to reflect new spec numbering

[kerimoyle]

Implementing the renumbering of the specifications document (as in https://github.com/cellml/cellml-specification/issues/24 ) means that we need to update the heading numbers given to errors/issues too.

[kerimoyle]

I've been going through how best to create nicely permanent bookmarks so that we can send users to a helpful URL based on the error code they get returned. I'd originally envisioned this being based on the section heading number (eg: B.4.2.1) but since we have a 1:1 correspondence between the Kind (or Cause) enum and these headings, I think it's cleaner to use the text of the enum instead. This means that changes to the numbering in the future won't automatically break everything throughout the docs and the library! If anyone has any vehement objections to that (or ideally, a better way to do it?) please let me know?

[hsorby]

I would have thought that it was equally likely to change the heading text as it was to change the heading number. So I don't think having links break because of changes is mitigated by using the heading text.

I find heading numbers more navigable for a document so my preference would be for heading numbers in text that is not hyper-linkable to the spec. document.

[kerimoyle]

I think that the numbers are a whole lot more fragile so it's not equally likely! The example of resets recently is a good one. We added two sections, deleted one, the numbers changed but none of the headings did ...

The way I see this working in practice is that we will show the user:

• an error message which is useful and sufficient, but also ...
• a URL to the informative documentation about where their error has gone against guidelines or the specification, and as well as that for the purists should they want to see the definitive rules ...
• a heading number in the specification.

It's mostly for constructing the URL that I'm thinking about how the error codes can be best used. This is the URL I'm playing with at the moment:

https://libcellml-tutorials.readthedocs.io/en/pr344_documentation/reference/specB01.html?issue=MODEL_CHILD

The use of the error enum string means that we can highlight the section of the spec which is relevant to the issue. At present it's still using the number of the section (here 01 comes from the model element being the first in section B). Obviously the root will change when it ends up in the final version, but hopefully you'll see what I'm going for.

[kerimoyle]

The changes needed for this issue are already present in this repo: we're just waiting for https://github.com/cellml/cellml-specification/pull/346 to be merged before they will function properly.