Rework simple and multilevel counters

[Omikhleia]

Closes #1536 - I suffered a bit on this one, so these are at least some proposals for review and scrutiny...

Things proposed here:

• Robutness checks added to counters:
  • SU.cast(), SU.boolean() checks, etc.
  • for multilevel counter, checks the passed level(s) vs. maximum (i.e. current) level.
• New options:
  • Add option noleadingzeros=true to multilevel counter formatting, to possibly skip leading zeros
• New commands:
  • set-multilevel-counter
• Proposed deprecations (the versions might have to be adapted)
  • \increment-counter[set-to=...]: it was not documented, and an increment that does a set is weird. We already have \set-counter for that, let's keep things simple, no?
  • \show-counter[display=...] and \show-multilevel-counter[display=...]: these are actually altering the counter, this does not seem expected on a "show" command which shouldn't have side effects, and we can already change the display format in a much more understandable way with the "set" or "increment" commands. Again, let's keep simple and clear. A "show" just shows without side-effects.
• Potential breaks:
  • I tried to make sense of the reset undocumented option on increment-multilevel-counter but it was pretty broken (it could not be used from SIL-language, as it was lacking a cast) and what it did when the passed level is greater than the current level did not seem right.
  • In the same case (level > current level), what it did was dubious (e.g. 1.3 set at level five would yield 1.3.3.3.1... I can't understand the rationale for repeating the previous levels); I changed it to something that seems more predictive (1.3.0.0.1), but this is breaking some tests. Are these really correct, though?

Things not yet done, for the record:

• Package documentation for the mutilevel counters. Will do, if we reach consensus regarding the above.
• Add test cases. Idem

Another unaddressed point I'd like to raise here: it doesn't seem logical to me to export some functions at class level (e.g. class:getCounter, while some aren't (well, still are, but deprecated, e.g. class:formatCounter). There's some hard-to-understand asymmetry.

[alerque]

I think this all makes sense.

Re tests: I would suggest Busted based unit tests rather than full page layout regression tests since we're after the math here more than the resulting typesetting.

Re class scope: The exporting stuff is mostly to support v0.13 classes and packages that didn't have another way to access functions from other packages. Now in v0.14 we do and it's possible we could eventually deprecate those exports entirely. For now I would leave the ones we have but encourage not adding any more unless absolutely necessary. Packages can now access other packages methods directly via self.class.packages["other-package"]:method. We could possibly even make that more ergonomic, but for now lets keep an eye on what we need it for so we know what to do with the existing export system.

The one caveat is exporting functions make it easy for them to access the class as self rather than the package, which might be a good reason to keep it for certain senarios.

[Omikhleia]

Updated:

• Added a bit more robustness (e.g. SU.required() and check on type of counters)
• Added multilevel counters to package doc
• Added busted tests. (N.B. There was no existing package, AFAIK, with busted tests, so I hope I did it the right way)
• Fixed existing text expectations.

[Omikhleia]

Omikhleia dismissed alerque’s stale review via e691329

Hmm. Not sure what I did here, it was unintended at best^^ Maybe the rebasing?
EDIT: Also, I have to find out how one declares co-authors in git commits. Digging the web

[alerque]

Hmm. Not sure what I did here, it was unintended at best^^ Maybe the rebasing?

I had commented on a specific line of code in the review. When you updated the PR tweaking that line it dismissed my review on the assumption that with updates I should review it again and see if what I commented was fixed. No problems here, just the way GitHub is supposed to work.

EDIT: Also, I have to find out how one declares co-authors in git commits. Digging the web

Git commits themselves have two basic properties: author and committer. Usually those are the same, but sometimes when you do things like rebase other people' commits you might become the committer while they stay as the author.

More recently GitHub and others (notably the 800 pound gorilla code review platform Gerrit) decided the 2 field system was restrictive, and started parsing the content of commit messages for more structured information. Editing these fields is just a matter of typing the expected text into the body of a commit message. You can even use multiples.

Some semi-standardized fields I know of:

Signed-off-by: Name <email>
Reported-by: Name <email>
Co-authored by: Name <email>

If GitHub detects a matching name/email that it knows about (probably just email?) it will show some UI goodies like linking their profile when relevant. They are not heavily used, but sometimes when somebody posts code in an issue but doesn't send a PR I find it nice to credit them. I usually just lookup the name/email pair they use on commits elsewhere and drop it in if I copy code from someone.

[alerque]

Looks great to me!

[alerque]

* Added busted tests. (N.B. There was no existing package, AFAIK, with busted tests, so I hope I did it the right way)

Yup that's exactly what I was thinking.

Also need to make sure that sort of layout works for 3rd party packages so external repos can be tested the same way without too much fuss. I'm guessing the easiest way to do this will be with nix. Then we should pretty easily be able to test a 3rd party module against an array of SILE versions (via tagged flakes) and also have busted on hand with whatever version(s) of Lua the 3rd party module supports.

[alerque]

I rewrote the commits (via advanced git rebase and git revise ninja foo) to split them up a little — mostly for the sake of the change log. In general, refactor: should indicate a different way to code exactly the same function and I have those commits suppressed in the release notes. In this case the overhaul changed the expected output (for the better) and also added options and functions, so I used fix: and feat: so that those changes show up automatically in the release notes. I didn't change any code, just mucked with the commit sequence.