Rearrange Intent section

[brucemiller]

This PR is a first attempt at rearranging the intent section to collect the various parts of definitions, descriptions and behaviors into single places to make the specification easier to use. Mostly, it collects the description of known, unknown, the how properties are used into a new subsection "Using Intent Concepts and Properties".

There is a gh-pages view here: https://brucemiller.github.io/mathml/spec.html#mixing_intent, although the numbering is not correct.

[davidcarlisle]

You could make respec happier by deleting the <dfn> (as you have done for element in the following item) or referencing it (as done for property on the previous item)

Found definition for "self-property-list", but nothing links to it. This is usually a spec bug!

[brucemiller]

Since you mention it: I had thought to make two changes to the grammar, but didn't want to go too far mixing changes.

• fold the self-property-list into the 1st intent line and remove the dt,dd,dfn completely, on the hopes that it is sufficiently described in the later section. It doesn't seem like it needs to called out explicitly (and is a slightly confusing name). Or, of course, simply remove the dfn wrapper if we'll never reference it.
• Change S to spaces to be infinitesimally more intuitive.

[davidcarlisle]

On the whole it looks good, there is one respec warning, and I added a suggestion at the point you indicated one was needed. (you can choose to add these or not to your PR using the "commit suggestion" button in the github UI.)

[davidcarlisle]

Suggested change

	<dt><dfn id="intent_property_list">self-property-list</dfn></dt>
	<dt>self-property-list</dt>

[davidcarlisle]

Suggested change

	<p><em>NEEDS CLARIFICATION: </em>
	<p>

[davidcarlisle]

Suggested change

	</p>
	For example an AT system might infer in intent of `power` given `<msup><mi>x</mi><mn>2</mn></msup>`,
	resulting in a reading such as "x squared". An explicit intent property of `:literal` could be used to over-ride this inferred intent, and lead to a reading such as `x superscript 2`.
	</p>

[brucemiller]

Right, could add that. But there's also the case of "short-hand" intent (if that's the right term): I was also concerned with a case like
<mrow><mi>x</mi><mo intent="plus">foo</mo><mi>y</mi></mrow>
which could be inferred to be
<mrow intent="plus:infix($x,$y)">...
Should this be addressed here? (or is it addressed elsewhere already?)

[NSoiffer]

@bruce: perhaps you could say that the two are equivalent (without inference)? But I think a more compelling example would be better -- an example where you would expect some inference. In general, an mrow will read as is unless some inference overrides it E.g., $|x|$ or or maybe $P(A|B)$. In the case of $|x|$, I don't think there is a markup analogous to what you wrote. I think if you wrote <mo intent="xxx">|</mo>, then I'm dubious AT would do a match that comes up with absolute-value -- MathCAT wouldn't.

One thought would be add more examples to the examples section and use them to illustrate some of the edge cases.

[brucemiller]

I just pushed a very dubious section as a starting point for discussion.

[davidcarlisle]

@brucemiller

fold the self-property-list into the 1st intent line and remove the dt,dd,dfn completel

I'm not sure. We ended up with that grammar after a rather tortuous iteration and it's managed to stay stable for some time now:-)

The grammar would be simpler if we dropped self-property-list and instead allowed term to be empty so that intent=":literal" was just a property on an empty term rather than a specific self-property, but the consensus was that allowing empty terms (everywhere) was too much so we are where we are.

As you say it's true that we could regard that as a grammar implementation detail and not make the description follow the grammar exactly but (at least in that section) I think it is clearer if it does, as it's describing the grammar rather than describing intent in general (I think....)

[davidcarlisle]

On S or spaces I don't mind, I was probably unconciously swayed by

https://www.w3.org/TR/xml/#NT-S

as the xml spec used S here

But if people prefer to change that, then any name is OK

[davidcarlisle]

ah yes I think we have so far avoided trying to specify how intents on operators are lifted up to have intents with arguments on inferred children (as infering the arguments proved tricky in general) perhaps you are right that just giving some examples as system specific inferred intents would be good.

maybe a new section (before the intent error handling section) on inferring intent?

[brucemiller]

Should I go ahead & create such a section, and add the suggestions we've discussed as a starting draft?

[davidcarlisle]

Should I go ahead & create such a section, and add the suggestions we've discussed as a starting draft?

I think so, this PR is "re-arrage intent section" not for any specific change so I think it makes sense to roll in other changes so people can see the section as a whole

[dginev]

To avoid disrupting discussion here, I have posed my remaining feedback as an add-on PR to this one, visible at brucemiller/mathml#1.

I am grateful for the changes in Bruce's commit 9902004 here, which gave me a foundation to build on.

[davidcarlisle]

on f3f9fec it may be worth copying (or perhaps even referencing) some of the examples in the intent-examples collecttion eg

https://w3c.github.io/mathml-docs/intent-examples/#id-1-1eff6f050a4d26222d07f68068e1014a

which shows "n choose k" being inferred from nothing (unless you use the :literal (nee :structure) property to suppress that.

[brucemiller]

It may indeed be worth copying some examples, but it would help to have a better sense of where we're trying to go with this section before getting too deep. In writing the "use of" section, the case of <mo intent="plus"> didn't quite fit: there are no explicit arguments. Maybe the containing mrow just gets read literally, and "plus" is spoken at the right time, without any concern of arity or fixity? Alternatively, if it is expected that intent="plus:infix($x,$y)" will somehow be inferred, we probably have to say something about how. Either way, something needs to be said, I think, just different things!

OTOH, for the case where no intent is given, I suspect that we should say as little as possible about inferring intent to avoid limiting implementers from finding the best magic that they can.

[davidcarlisle]

It may indeed be worth copying some examples, but it would help to have a better sense of where we're trying to go with this section before getting too deep. In writing the "use of" section, the case of <mo intent="plus"> didn't quite fit: there are no explicit arguments. Maybe the containing mrow just gets read literally, and "plus" is spoken at the right time, without any concern of arity or fixity?

Yes, I think there are two possible models there.

• one (which is I think what the spec says now) <mo intent="plus"> is a zero-arity plus and that may or may not have a special rule or may just get read as literal plus.

• the other (which might be useful but we certainly don't want to specify, leaving it up to implementatiions, is that the system decides that plus is infix binary, so infers its arguments from siblings (if there are any) and basically re-writes to intent=plus{$a,$b) on the parent mrow.

Alternatively, if it is expected that intent="plus:infix($x,$y)" will somehow be inferred, we probably have to say something about how. Either way, something needs to be said, I think, just different things!

yes although I suspect we can't say "how" without falling into old rabbit holes around which element siblings are likely arguments and which are just punctuation

OTOH, for the case where no intent is given, I suspect that we should say as little as possible about inferring intent to avoid limiting implementers from finding the best magic that they can.

yes I think though we should say it's allowed. One real problem I had making the intent examples was that mathcat often made a good reading of the original, no-intent version, and then I struggled to add intent in a way not to mess it up. We need to say I think that systems may infer intents either if there are no intents at all or if the intent markup is only partial with not all subterms annotated. The system SHOULD not do that if a :literal property is in scope but otherwise they have free rein to do anything?

[brucemiller]

Yes, I think there are two possible models there.
* one (which is I think what the spec says now) <mo intent="plus">is a zero-arityplusand that may or may not have a special rule or may just get read as literalplus`.

Yeah, this is where my thinking was gradually headed, I think. I didn't find it addressed explicitly anywhere, but certainly implied in examples. Probably at the beginning of the Using section we need a bit of clarification along the lines that arity & fixity are only relevant if arguments are given explicitly in the intent form. And the effective speech hint is going to look like the existing ones, except omitting any "of", commas, arguments and such. Perhaps some concepts will want an explicit extra entry? Some won't make sense in any event (as @NSoiffer pointed out).

If we can phrase this right, we probably don't need this new section at all.

* the other ....

The possibility of making the detailed intent completely explicit belongs with the possibility of inferring a intent from scratch: we'd want to allow it, but not get into any details.

[davidcarlisle]

The possibility of making the detailed intent completely explicit belongs with the possibility of inferring a intent from scratch: we'd want to allow it, but not get into any details.

yes, so I suppose it's a choice of whether we assume anything not forbidden is allowed, and so not mention it or whether we want to give a note that it is allowed and possibly even a an example or two.

[brucemiller]

Following the above discussion, I just added some clarification to the beginning of the Using section about matching intents which have no arguments, which (mostly) handles the common case of <mo intent="plus">. It may be that we need to either add arity=0 cases to the dictionaries, or otherwise comment on not saying "integral of"?

Consequently, I've removed the stub section on inference (we can add more later, if needed).

[davidcarlisle]

one trivial typo marked in line (si/is) but otherwise last round of changes look good

[NSoiffer]

I think this is a very good rewrite. There is more work to do (e.g., add some text on :literal). But this is a good rearrangement of the material and clarifies that Intent Concept Dictionary is a general idea that can be implemented in a wide variety of ways.

[davidcarlisle]

@brucemiller @NSoiffer not sure why the pipeline is failing (the spec seems to have built and pushed to gh-pages)

[davidcarlisle]

I'm not quite sure what it was saying, but the failure seems to be an artifact of the fork/PR.
Builds all green again now.