Distinguishing arguments in intent concept lists

[davidcarlisle]

In both core and open intent concept lists it's not always immediately obvious which arguments are which.

We have added some wording to sugest that $1, $2, .. should be chosen based on the order in the presentation mathml markup for the suggested notation, but that still leaves a lot of room for confusion.

I'll use the examples from the PR for the open list as that has the most mathml currently but the issue applies to core list as well.

rooted-product-of-graphs is X∘Y so it's not to hard to guess that the intention is that X is the first argument and Y is the second argument in the rooted-product-of-graphs($a,$b) form

But for example

superfluous-submodule is $X \subseteq_s Y$ and you have to know the X and Y are the variables (in that order) and that s is part of the syntax.

I can think of two ways to possibly inprove this, we could do one or both (or neither)

• Always use $1 , $2 ... as the variables in the displayed notation, acting as template slots matching the use in the speech templates so show $\mathtt{\$1} \subseteq_s \mathtt{\$2}$ not $X \subseteq_s Y$

• Use intents in the MathML source (which might not show in the rendered form but would be available to anyone looking at implementing the list).

So use

<math><mrow><mi>$1</mi><mo>∘</mo><mi>$2</mi></mrow></math>

or

<math><mrow intent="rooted-product-of-graphs($a,$b)"><mi arg="a">X</mi><mo>∘</mo><mi arg="b">Y</mi></mrow></math>

instead of

<math><mrow><mi>X</mi><mo>∘</mo><mi>Y</mi></mrow></math>

[davidcarlisle]

After discussing this on todays call, I implemented this with some brutally simplistic css

specifically adding

     [arg]:hover {background-color: beige;}
     [arg="a1"]:hover::after { content: " $1" ; }
     [arg="a2"]:hover::after { content: " $2" ; }
     [arg="a3"]:hover::after { content: " $3" ; }
     [arg="a4"]:hover::after { content: " $4" ; }

and no changes to the liquid templating at all.

In firefox this puts $1 next to the variable on hover, and in chrome based browsers it comes below. In the fork on my site I added arg='a1' to every <mi>x or <mi>X and the same with a2 for y and Y. as that was easy to do.

Obviously the css could be tweaked or we could add some javascript but does this look reasonable as a first attempt and enough to form a basis for the harder work of actually adding all the intents.

https://davidcarlisle.github.io/mathml-docs/intent-open-concepts

Hovering over Ai X:

[dginev]

Some more CSS ideas:

• show the on-hover args as scripted and smaller font size
• generalize by directly using the attribute value (with a $ prefix)
• extend the showcase to also offer the intent attribute (without $)
• color code arg differently from intent

For example:

[arg]:hover { background-color: #add8e6;}
[arg]:hover::after {
  content: " $" attr(arg);
  vertical-align: sub;
  font-size: 0.7em; 
}
[intent]:hover { background-color: #90EE90;}
[intent]:hover::after {
  content: " " attr(intent);
  vertical-align: sub;
  font-size: 0.7em; 
}

[davidcarlisle]

@dginev yes I tried something like content: " $" attr(arg); first but it makes $a1 which doesn't match the $1 we use in speech templates (we could change that of course, but $1 looks better than $a1 there I think)

The problem with [intent]:hover is that in most cases it's the whole expression, and overlaps the hover on arg (which isn't an error but may be confusing) (a secondary issue is that there is only one intent added so far, as they are harder to add) but anyway I'll add your versions, let's see how it goes...

[dginev]

For developers, it would eventually be useful to have a toggle button that makes all of these arg/intent values visible globally for the page, so that we don't have to hover over 1000 entries. Hidden by default seems reasonable.

CSS may also be a nice approach to mark with some color entries that haven't yet been annotated. Something like:

math:not(:has(*[intent])) {
    color: red;
}

---

(we could change that of course, but $1 looks better than $a1 there I think)

Indeed arg="1" and intent="$1" appear to be productive/natural in various settings, which is part of why I wished we had numbers available in those slots.

I think they fit even more naturally now when at least the Open list has guidelines about selecting the argument order (which can be thought of as a sequential 1,2,3,... traversal over the presentation tree).

Absent that, your solution does the job, although maybe it should go upto 9 just in case.

[davidcarlisle]

@dginev

Absent that, your solution does the job, although maybe it should go upto 9 just in case.

well at any given time its known what the highest number is in the file so we can add as many as needed.

I have marked (with a lighter background than on hover) the mi that have arg which proved quite useful in spotting some missed cases.

Also I have added intent= in most (or at least a lot) cases.

I'm not sure it helps to have the intent values shown as in any row you know what that will be from the first two columns, content foo arity 3 will have intent=foo($a1,$a2,$a3)

I agree not having to hover to see the arg would be good, although I don't think having the $1 markers in the display would be that useful (to me at least) what might be useful (and probably easy to add) would be an option to show the verbatim source mathml rather than the rendered view, either for a single expression or the whole page?

But we can add such display improvements later, so long as we get a current display that's good enough now to do the harder job of actually checking the lists.

If this is moving in the right direction I'd like to merge, even though it's incomplete, so others can edit this version further rather than the "main version" being just in my fork.

[davidcarlisle]

@dginev I added your css to flag missing intent:

[davidcarlisle]

@dginev no red left, intents added to all examples/

[dginev]

Nice. Since that was of interest, I can offer two more validation CSS rules - one checking if a $ref was used in intent without having an arg, the second whether an arg="ref" was never used / remained dangling. For now following the a1-a9 naming convention:

[intent*="$a1"]:not(:has([arg="a1"])),
[intent*="$a2"]:not(:has([arg="a2"])),
[intent*="$a3"]:not(:has([arg="a3"])),
[intent*="$a4"]:not(:has([arg="a4"])),
[intent*="$a5"]:not(:has([arg="a5"])),
[intent*="$a6"]:not(:has([arg="a6"])),
[intent*="$a7"]:not(:has([arg="a7"])),
[intent*="$a8"]:not(:has([arg="a8"])),
[intent*="$a9"]:not(:has([arg="a9"])) {
  color: orangered;
}

[intent]:not([intent*="$a1"]):has([arg="a1"]),
[intent]:not([intent*="$a2"]):has([arg="a2"]),
[intent]:not([intent*="$a3"]):has([arg="a3"]),
[intent]:not([intent*="$a4"]):has([arg="a4"]),
[intent]:not([intent*="$a5"]):has([arg="a5"]),
[intent]:not([intent*="$a6"]):has([arg="a6"]),
[intent]:not([intent*="$a7"]):has([arg="a7"]),
[intent]:not([intent*="$a8"]):has([arg="a8"]),
[intent]:not([intent*="$a9"]):has([arg="a9"]) {
  color: orange;
}

Aside: There may be better colors than the example ones I picked in haste. Aside 2: There seems to be an unbalanced closing brace in the current inline CSS at the forked page demo.

[davidcarlisle]

@dginev yes I keep changing my mind about "validation by css" it may prove useful going forward as a kind of quick check on submissions, when doing bulk edits like today it's better to do eg

$ grep '<math>' open.yml | grep -v intent

which is what I used to get everything with intent not scrolling the page looking for red bits, but both have their uses.

Thanks for spotting the } though, I just zapped it.

The fork is way too far ahead of the upstream though, and I need to do something else, any objection to me merging as it is now?

[davidcarlisle]

@dginev there were 182 left where the notation hints were not sufficiently regular to automatically make mathml and will need to be hand tuned, checking the source URL that you originally provided.

To make the hand editing a bit easier I generated a stub mathml with the required intent with the correct concept name and arity in each case, all of the form !!F($a1) or !!F($a1,$a2) marked in red. the original notation: yaml fields are still there in these cases.

This now displays at

https://davidcarlisle.github.io/mathml-docs/intent-open-concepts/#periodic-continued-fraction1mfrac

and is ready to be merged at pull request https://github.com/w3c/mathml-docs/pull/67

I think the remaining edits can be done after a merge.

[davidcarlisle]

I added a show mathml source button replacing every rendered math element by a div showing its source

Currently just one global switch if people like it it could be extended to toggle on and off or be an option for each math expression individually, or whatever, but it is I think enough for now.

[davidcarlisle]

while we can tweak the exact details I think the basic principle of distinguishing the arguments using intent markup is established, so closing here.