Process for typographical corrections in openEHR specifications

Hi,

I occasionally read through the various openEHR specifications for the sake of learning about the health IT domain. While doing so I sometimes find typographical mistakes, Asciidoc syntax problems, or broken links.

Since one pull request fixing typos was merged but others don’t receive feedback on GitHub (since 13 Aug and 21 Sep) and I am wondering whether it’s worth the time to resolve merge conflicts and create new pull requests like this.

Could you please tell me what’s your take on fixing such small issues? And if you agree that fixing them is worthwhile, what is the appropriate process for this?

Kind regards,

Jan

Jan,
This is our fault for not regularly looking for pull requests on the actual repos. I have now merged your changes, some by manual means, due to too many intervening changes preventing a machine merge.

These kinds of fixes are highly appreciated, and I am slightly horrified to discover so many remaining typos (some probably there for years). So thanks for taking the time to make them. We’ll be much more vigilant in the future on pull requests. Historically typos got fixed within other CRs, rather than via pull requests, but that’s changing thankfully. Next time you may have similar change to offer, please make a bit of noise here, just in case we miss the email from Github (which we sometimes do).

BTW, we normally include an entry in the Acknowledgements list (example) for every person who ever caused a change to the specs. If you are happy to be included there, can you please send me (email) your position, org, and any higher degree (PhD etc)? Note: your name is already in the normal amendment record on the affect specs, as you will see in a day or so.

Anyway, the CR containing your changes is here. In a day or so you’ll see commits with all the changes.

Great work! We’ll get the next changes in time and hopefully via machine merge.

2 Likes

Sorry for hijacking this thread, but this is nothing I can resolve myself and suggest as PR nor it is a specific discussion regarding a specification subject (maybe a sticky thread for such things aside typos would make sense?):

I found a dead reference here: https://specifications.openehr.org/releases/BASE/latest/base_types.html#_identifying_versions_within_openehr_versioned_containers

and reverse internet domain identifiers, as recommended in [3]

The “[3]” is not a hyperlink and it appears to be a left over since there are no “[1]” nor “[2]”. There’s no other kind of bibliography at all. Can you restore what “[3]” was pointing to @thomas.beale ? I was trying to find it in the git history but wasn’t successful.

Yep the references are not 100% fixed from the changeover from FrameMaker to AsciiDoctor. Anyway, if you want to follow that ref, it is probably this one:

Hnìtynka P, Plášil F. Distributed Versioning Model for MOF. Proceedings of WISICT 2004, Cancun, Mexico, A volume in the ACM international conference proceedings series, published by Computer Science Press, Trinity College Dublin Ireland, 2004.

Or maybe not… I tracked back through the original PDF generated from Frame, and even in that, the [3] doesn’t refer to anything, which is odd, because Frame always gets that right. This means it is probably a direct text copy and paste from some other place. So I don’t know what this originally referred to, but I guess reverse domain names are not controversial! For now I will just delete this reference from the text.

1 Like

@thomas.beale So, shall I continue posting those “no simple typo but also not regarding the spec semantically” bugs here?

Anyway, all the “tc_ehr-*” and “Postman” links on the right side are broken here:
https://specifications.openehr.org/releases/CNF/latest/openehr_platform_conformance.html#_ehr_persistence_component

Yep this spec is awaiting a rewrite on that part of the table, using the input from the Vita/HighMed project, where they have actually implemented all this. Hopefully soon. Your project :wink:

1 Like

@thomas.beale Here is another one:

https://specifications.openehr.org/releases/BASE/latest/base_types.html#_object_ref_class
a string matching the regex [a-zA-Z][a-zA-Z0-9_-:/&+?]*

The given regex pattern appears to be wrong, at least its format. IntelliJ (maybe it is the SonarLint plugin) and some other tool (https://www.regextester.com/) are giving me an error when using [a-zA-Z][a-zA-Z0-9_-:/&+?]* as pattern. It says the _-: part is parsed as a range, while having a wrong range (_ to : is not working because of their order).

Is this meant to mean “… or _ or , or : or …”? Then I would simply propose to change the pattern to: [a-zA-Z][a-zA-Z0-9-_:/&+?]*. This pattern goes through both tools without an error.

It should allow dashes (’-’) and underscores. From memory, a literal dash needs to be the last character in an equivalence class in regex, which I think is the error. Try putting it at the end. I created a CR for this - https://openehr.atlassian.net/browse/SPECBASE-27.

2 Likes

The minus is a special character in regex ranges and should be escaped. I’ve added a proposal in the CR

1 Like

And a more typographical one @thomas.beale:

https://specifications.openehr.org/releases/RM/latest/common.html#_party_identified_class says

0…1 - identifiers: List<DV_IDENTIFIER> - One or more formal identifiers (possibly computable).

One or more is mismatching with 0..1.

PS: Notify me if I should change this process of reporting.

Well actually that one is a bit more subtle - the List is optional, but if it is there, then it has to have something in it. I guess we should really say ‘zero or more’…

BTW you now access to the SEC category, as an SEC-experts member, so you can post within that group.