search

cellml / libcellml

Repository for libCellML development.
https://libcellml.org
Apache License 2.0
17 stars 21 forks source link

Re-encode all SpecificationHeadings to reflect new spec numbering #562

Open kerimoyle opened 4 years ago

kerimoyle commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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:

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 commented 3 years ago

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.