The Scala language spec (SLS), https://scala-lang.org/files/archive/spec/2.13/, has identifiers for its sections (and sub-sections) so, for instance, SLS 8.5 is about “Pattern Matching Anonymous Functions”: https://scala-lang.org/files/archive/spec/2.13/08-pattern-matching.html#pattern-matching-anonymous-functions.
I’ve seen people refer to sections of the spec by such numbers (e.g. “as defined in SLS 8.5”) however I was surprised to see that those numbers are derived and don’t actually exist in the source: https://github.com/scala/scala/blob/v2.13.0/spec/08-pattern-matching.md#pattern-matching-anonymous-functions. Meaning that “8.5” could refer to something else (let’s say within the 2.13 spec alone) if a section is added or if a section is removed (such as two sections merging into one).
Do we have a system in place to prevent this? Is it just part of the spec upkeep to safeguard against any such section changes within a major (e.g. 2.13) version of Scala?
My initial idea was to manually number the sections so that any changes would be more clear and obvious, but do you think that’s worth it or a good idea? A side-benefit would be that I wouldn’t need to see a rendered version (or, worst yet, manually count) to figure out in 08-pattern-matching.md which section is “SLS 8.5”.
Thanks,
Dale
5 Likes
Sounds like a valid concern.
I would give every chapter and section a mnemonic identifier, so we could refer to sections not by numbers, but mnemonics (like “Section PatMat-AnoFun” instead of “Section 8.5”).
2 Likes
I agree with @curoli – having stable identifiers seems like a very good idea, but reifying section numbers just seems like a long-term maintenance nightmare. (What happens when a new section gets inserted? We wind up with section numbers that are out of order?)
Requiring a brief mnemonic for each section, and providing a stable way to find sections by that mnemonic, though, would probably be a win, if we could make it work…
3 Likes
My initial idea was to manually number the sections so that any changes would be more clear and obvious, but do you think that’s worth it or a good idea?
Mnemonic identifiers aren’t absurd, but I couldn’t quite imagine how to manually number things… EDIT: do I miss something? Except that (Italian) laws do it (see below).
In any case, I’m a fan of not reinventing the wheel, so here are some existing solutions.
- Permalinks are a thing, does the spec have good ones?
- You can cite an edition/version of the spec. That’s the standard for bibliographic references, and I think is also used for software standards (say, the C/C++ one). We usually don’t specify a number, but I suspect we get away because the spec hasn’t been renumbered in ages.
- With (Italian?) laws, the article numbering is frozen at the “first release”. Inserted articles get special numbering — e.g. an article between art. 2 and art. 3 gets called 2bis (and so on, using Latin numbers). We won’t use Latin numbers, but if you really want to “manually number things”, some variant could work? One could use fractions, but I’m not sure I like the idea.
But technically, does Markdown even allow any custom numbering?
I don’t understand where “2bis” comes from, or how one would “go on with Latin numbers”?
In German law (and also for numbering houses in a street), if you want to insert an article between 2 and 3, it would be called 2a, and if one would be inserted between 2a and 3, it would be 2b. I’m not sure how to call articles inserted between 2 and 2a, or between 2a and 2b - I suspect the system does not scale well with a large number of changes.
Perhaps decimals would not be a bad idea at all, so between 2 and 3 is 2.5, and then between 2 and 2.5 is 2.2, etc.
Also, in German law, if an article gets removed, you leave behind a note saying so (e.g. “Article 5: [repealed]”).
In American law, I think, you don’t ever change a law, you just pass some amendment that says that the law is now different. An updated annotated edition of the law would of course have a footnote noting that some part has been repealed. There is a reason American lawyers are paid well.