textmetrics: Release ready

[kintel]

Make textmetrics() release ready:

• Final API validation
• Move out of experimental
• Validate test coverage
• Manual entry
• Cheat sheet entry

Main release checklist: #3640

[jordanbrown0]

• API validation: somebody else needs to do that. I was happy with it when I PRed it, or I wouldn't have.
• Test coverage: I did include a few tests (tests/data/scad/2D/features/text-metrics.scad, tests/data/scad/misc/text-metrics-test.scad). Looking at them now, they could be a bit more comprehensive:
  • With and without descenders.
  • With and without characters that go above the midline.
  • Characters where the lowest point is above the baseline. (I think these currently behave strangely with valign=bottom.)
  • All 4x3 alignment types.
  • RTL, LTR, TTB, BTT. (But TTB and BTT are known to have suboptimal alignment behaviors.)
• Manual: how do we do development-snapshot manual work? Just mark as "require development snapshot"?
• Cheat sheet: where is it? PR to openscad/openscad.github.com?

I can work on tests and docs.

[kintel]

• Manual: how do we do development-snapshot manual work? Just mark as "require development snapshot"?

We've been using {{requires|Development snapshot}} - see e.g. https://en.wikibooks.org/w/index.php?title=OpenSCAD_User_Manual/User-Defined_Functions_and_Modules&diff=prev&oldid=3806773

[kintel]

• Cheat sheet: where is it? PR to openscad/openscad.github.com?

Yes, we have one for the latest release, and one for the snapshot:
https://github.com/openscad/openscad.github.com/tree/main/cheatsheet

[kintel]

• API validation: somebody else needs to do that. I was happy with it when I PRed it, or I wouldn't have.

Yeah, agreed - just want to take a look with fresh eyes and try to break any corner cases :)

[jordanbrown0]

Cheat sheet updates in PR#144.
Doc updates at
https://en.wikibooks.org/wiki/Special:Contributions/Jordan_Brown
31 December 2024, 01:33 through 05:13 UTC.

[jordanbrown0]

Opinions on whether we need more tests?

[kintel]

Let's wait for the API validation. If I end up doing that, I might discover what I feel needs more tests.

[jordanbrown0]

Perhaps the most significant API question is the API surrounding objects/dictionaries. See OEP8 for a writeup of that, though OEP8 also includes other stuff.

Capsule summary:
obj.key retrieves item named key, where key is a legal identifier.
obj[expr] retrieves item named with the value of expr, with no restrictions on syntax.
for (k = obj) iterates across obj, assigning each item name to k.
str(obj) and echo(obj) dump obj in OEP8 syntax.
is_object(v) returns true for objects.

Note that this API question is probably the key question for import("foo.json") too.