w3c / mathml

MathML4 editors draft
https://w3c.github.io/mathml/
Other
58 stars 18 forks source link

open concept list issues #497

Open davidcarlisle opened 2 weeks ago

davidcarlisle commented 2 weeks ago

Now the first pass over the open list has been made providing mathml/intent examples some general issues are noticeable that on the call of 2024-06-20 I agreed to note in an issue here.

I'll give links to examples in the open list although those links may break over time as things are adjusted. I'm listing them here as a single meta-issue rather than opening separate issues for each problematic entry as fixing the entries is probably easy once the basic principles are agreed.

Unrelated concepts with same name combined.

I don't think there are many instances in the current list but one is barrel which is used for both the archaic unit and barrelled space.

This kind of accidental clash is the easiest to fix, we simply need to separate a new row, say baralled-space for the vector space concept.

Related concepts combined with same concept name,

There are many more of these and more options on how to fix.

error-function has both erf and erfc

modified-spherical-bessel-function has examples with different letters for the different kinds unlike the standard bessel function which has separate entries for first and second kind. These could be split into separate named concepts ...first-kind or an extra kind argument added so (1,x) or (2,x) that does not correspnd to an argument in the normal notation but to the function letter used.

Indexed functions

There are many indexed functions say $W_n(x)$ denoting the "n-th wibble function of x" some are coded as arity 2 so wibble(n,x) some as arity 1 wibble(n) and some as both. The arity 1 form is needed to discuss the abstract function, $W_n$, the application could then be encoded using a constructed function head: wibble($n)($x) but it (might?) be more natural to allow an arity 2 form wibble($n,$x).

If we want that, rather than duplicate the entries for multiple concepts it might be possible to have a meta-templace listing arity [1/2] with a speech template that makes it clear the template is "n-th wibble function" if used with 1 argument and "nth-wibble function of x" if used with two.

Sometimes there is more than one annotation so it might be arity [2/3] for $W_{i,j}(x)$ for example.

Differential operators

The markup for differentiation is being discussed elsewhere #473 and would affect some entries here

n-ary operators

The markup for n-ary operators and quantifiers is being discussed #482 elsewhere and would affect several entries here. This is similar to the indexed function case listed above as these operators typically take multiple arguments in a way that can possibly be formalised to give a mor compact listing eg arity 0 sum, arity 1 sum over $X arity 2 sum from $a to $b , sum from $a to $b of f(x) ... etc.

Simple errors

The above describe structural issues, but apart from that there are almost certainly simple errors/typos that could benefit from review.edits. the current list has 1012 concepts and 1300 mathml examples that have been semi automatically extracted from the original sources and semi automatically converted from google docs to yaml and added mathml + intent. Some level of validation has been done but some will be wrong.

dginev commented 2 weeks ago

To add two more:

Entries which should be Properties

As the seeding list predates the "property" capability of intent, its coverage is too broad. An example is bijection, which is typically a kind of relation, as with f:bijection.

These should either get completely erased, or moved to a separate "Open Properties" resource.

Argument order errors

For entries with >1 arguments, it is important that the "speech template" and "notation" (Comments??) columns agree. For example, in amalgamated-product, the presentation order is A, then C, then B, so they ought to map to $1,$2,$3 (currently C is $3) with the (currently correct) speech template "Free product with amalgamation of $1 and $3 with respect to $2".

davidcarlisle commented 2 weeks ago

@dginev I don't think there is a general rule that the speech order matches the visual presentation and it certainly doesn't aways match the mathml markup order, especially when prescripts are involved and mathml order is completely different to the visual presentation. So while the $1, $2`$3 will often appear in the same orders in the speech template and the mathml rendering that certainly can't be a fixed rule.

On your "comments?" aside yes I wondered about that... The use of that column has evolved actually it allows free text comments, plus the mathml fragments and then any aliases. Now the formal mathml is in place it probably makes sense to separate them at least in the yaml and have comments field for free text and mathml (or notation) field for the rendering examples, the yaml could be used to generate separate columns but then the columns get very narrow or you have to scroll so merging the yaml fields into one column seems ok, but open to other suggested layouts

davidcarlisle commented 2 weeks ago

@dginev oh notwithstanding my comments that the orders can't always agree, the current entry for amalgamated product is, as you say, wrong.

dginev commented 2 weeks ago

@dginev I don't think there is a general rule that the speech order matches the visual presentation

@davidcarlisle Did I write something to that effect? My comment was following the now agreed rule at the top of the Open list:

Unless otherwise noted below, the argument order of the concepts follows the order used by the presentation MathML elements that are typically used represent the concept.

As mentioned, A, C and B appear in that order in the presentation of that particular notation, so they ought to get $1, $2, $3 respectively. How the speech template uses those variables can be in any order that sounds good to an English speaker.

davidcarlisle commented 2 weeks ago

@dginev on "(Comments??)" I have separated these in the yaml with free text comments under comments: (which passes through the markdown filter) and moved the mathml to a new mathml: field (which is not run through markdownify) currently at least, the display is unchanged with comments, mathml and aliases all sharing a column, but having these distinct in the yaml seems better. Currently there is only one comments entry (in long division where I didn't do a mathml version pending a descision on whether it could use <mlongdiv or should use mathml core)

NSoiffer commented 1 week ago

The notation really isn't the same as a comment, so I think it makes sense to make it a separate column. For someone new to editing the list, it would be clearer.

Two other things:

  1. The "Show MathML" button needs to be a toggle -- it doesn't go back to showing the displayed MathML.
  2. The first sentence/paragraph is no longer needed ("This open list sketch has been extracted from the google spreadsheet and is not exactly in the format of the core list but hopefully close enough to be useful.")
davidcarlisle commented 1 week ago

@NSoiffer

The notation really isn't the same as a comment, so I think it makes sense to make it a separate column. For someone new to editing the list, it would be clearer.

Yes, I split things in the yaml so there are currently 1300 mathml: and 1 comments: fields in the yaml.

They are currently recombined into the same column in the display as a more or less empty comments columns adds a lot of width to the table and I was trying to avoid impossibly small fonts or requiring horizontal scrolling. Perhaps comments could trigger a second line spanning all the columns of that entry? I'm not sure, layout suggestions welcome.

Two other things:

1. The "Show MathML" button needs to be a toggle -- it doesn't go back to showing the displayed MathML.

Yes you can refresh the page to get back but I agree that's not too friendly. I don't really like it at the top at all: if you are 1000 rows down looking at the rendered mathml you need to go all the way to the top, flip the display, then re-find the entry you want. The code could trivially be made to just toggle the display of a single mathml element, but as above I couldn't find a good UI. Perhaps instead of a button there should be a keyboard shortcut, although I'm not sure of the accessibility implications of such an interface.

2. The first sentence/paragraph is no longer needed ("This open list sketch has been extracted from the google spreadsheet and is not exactly in the format of the [core list](https://w3c.github.io/mathml-docs/core) but hopefully close enough to be useful.")

I'll zap that.