Repository navigation
Add examples to core concepts #537
Description
There are probably many things that need to be worked on in the Concepts and Properties lists. Adding notational examples to all of the entries is one of those things.
This issue was motivated by a discussion with someone on intents and seeing that just because there was an intent name, it isn't clear to non-MathML "natives" what notation(s) the concept refers to. A minority of entries have examples, so there is plenty of work to do to done.
Currently, the examples that exist are in the "comments" column. Perhaps there should be a separate "example notations" column?
Activity
davidcarlisle commentedon Jul 10, 2025
while I have no objection to examples I think we need to carefully introduce then as examples as the answer to
is: "it does not refer to notation at all"
An important use of intent concepts is surely to specify the concept (intended meaning/reading) when the notation is unusual.
that said the current examples would be clearer in their own column.
If doing that we should change the yaml rather than try to "spot" example in comments entries in the liquid templating.
Adding another column would probably cause issues with the current layout especially if more than one language is being shown, which adds even more columns
I would suggest that in the desktop layout we allow the table to go full width not constrained as now to a typeset block width
On mobile it's probably not really usable anyway but we should make sure that it is in principle usable with enough scrolling
NSoiffer commentedon Jul 10, 2025
I agree with that, but there are common notations (sometimes more than one) associated with the concept.
evaluated-athas example notations and something like that is what I think should be added for all notations.For something like$x^2$ , $x^3$ , and $x^n$ can all be listed. For intervals, we can show $(1,3)$ and $]1,3[$ (hopefully I have the equivalence right).
power,davidcarlisle commentedon Jun 26, 2026
This isn't quite the right issue but has overlaps, so I'll raise here. In a recent call it was suggested that we change the
$1,$2in the current speech hints, and @dginev was going to have a look at making the first pass of that.Looking at the list now I think I'm still somewhat against that suggestion. The
$1as used in the current core and open lists is not an invalidintentargument, it's never used in an intent expression. It's a useful meta-syntax in the speech hints referring to the (speech generated by) the first argument.We should document that in the introductory paragraphs but I don't think we should change the syntax.
Currently for example
https://w3c.github.io/mathml-docs/intent-core-concepts/#closed-interval2function
has
closed interval between $1 and $2so you know exactly how to generate the speech hint for
closed-interval(0,1)That row doesn't currently have an example MathML but if we changed the speech hint to be
closed interval between $lower and $upperand added an example something like
<mrow intent="closed-interval($lower,$upper)">...getting the information would be harder, you'd have to find the example, and navigate it to find an
intentexpression, then generate a mapping from the names used in the example.We could use the conventional names
$arg1, $arg2, ...as we do in (some) of the existing examples so just replace$1by$arg1everywhere, but I don't really think that clarifies anything. It would however allow the same description that$arg2refers to the second positional argument without introducing a specific name such as$upperthen needing an example to show that's the second argument.dginev commentedon Jun 26, 2026
It is/will be used in the intent expressions of the new Open list contribution interface, hence the change there.
davidcarlisle commentedon Jun 26, 2026
@dginev I raised the issue to make sure we don't lose functionality but there are several ways this could be coded of course.
I just tried the test editor interface and if I understand correctly you are using
$a1which is fine (obviously structurally equivalent to the$arg1I mention above).certainly if we go with that on the open list we should do the same in the core list.
davidcarlisle commentedon Oct 27, 2026
the PR at w3c/mathml-docs#97 re-arranges the core property list yaml to use (mostly)
$a1instead of$1and adds anarguments:field giving the argument order. the$a1,$a2naming isn't assumed and individual entries could be changed to$numerator$denominatoror whatever, but it's a convenience for mass-converting from the$1,$2, ... format.