Tutorials: Simplify file validation (xpath / relaxNG )

[musicEnfanthen]

In https://github.com/music-encoding/music-encoding.github.io/pull/57#issuecomment-444919079 @kepper adressed the issue of simplifying the validation steps of the tutorial:

Btw., @lpugin has found a way to validate against RelaxNG on the client. I don't know how performant that is, and it surely creates less helpful error messages, but together with an MEI-all-anystart.rng, this could greatly simplify the writing of tutorials and reduce the number of xpaths…

@lpugin answered in https://github.com/music-encoding/music-encoding.github.io/pull/57#issuecomment-445162123

Yes: https://jsfiddle.net/lpugin/rmc18zkw/17/ It should be no problem to use anystart.rng . I will test it and see if we can get it integrated in the jekyll website.

To keep things separated, let's further discuss the issue of simplifying file validation on the client side here.

[musicEnfanthen]

At the moment writing, the user input in the tutorials is validated via xpath expressions predefined by the tutorial authors like so:

"xpaths": [
        {"rule": "count(//mei:scoreDef) = 1", "renderanyway": false, "hint": "You need one scoreDef element."},
        {"rule": "count(//mei:staffGrp) = 1", "renderanyway": false, "hint": "You need one staffGroup element."},
        {"rule": "//mei:scoreDef/mei:staffGrp", "renderanyway": false, "hint": "staffGrp element has to be a child of scoreDef element."},
        {"rule": "count(//mei:staffDef) = 1", "renderanyway": false, "hint": "You need one staffDef element."},
        {"rule": "//mei:staffGrp/mei:staffDef", "renderanyway": false, "hint": "staffDef element has to be a child of staffGrp element."},
        {"rule": "count(//mei:scoreDef/@*) = 2", "renderanyway": false, "hint": "You need two attributes on scoreDef (@key.sig & @meter.sym)."},
        {"rule": "//mei:scoreDef/@key.sig = '3f'", "renderanyway": false, "hint": "You need a @key.sig attribute with a value of 3f."},
        {"rule": "//mei:scoreDef/@meter.sym = 'cut'", "renderanyway": false, "hint": "You need an @meter.sym attribute with a value of cut."},
        {"rule": "count(//mei:staffDef/@*) = 4", "renderanyway": false, "hint": "You need four attributes on staffDef (@n, @lines, @clef.shape & @clef.line)."},
        {"rule": "//mei:staffDef/@n = '1'", "renderanyway": false, "hint": "You need a @n attribute with a value of 1."},
        {"rule": "//mei:staffDef/@lines = '5'", "renderanyway": false, "hint": "You need a @lines attribute with a value of 5."},
        {"rule": "//mei:staffDef/@clef.shape = 'G'", "renderanyway": false, "hint": "You need a @clef.shape attribute with a value of G."},
        {"rule": "//mei:staffDef/@clef.line = '2'", "renderanyway": false, "hint": "You need a @clef.line attribute with a value of 2."}
]

[musicEnfanthen]

After having written about 390 of these rules for the march tutorial, I can tell that on the one hand this is

• the most time consuming part and
• probably the biggest obstacle for forthcoming tutorial authors
• another confusing potential: e.g. if the user is supposed to insert one measure in a row of predefined measures (let's say: "Please encode the third measure of the example"), you have to check for 3 measures (of the whole file) instead of only 1 measure (of the user input)

On the other hand, it gives you

• quite a precise and granular control about what you want the user to insert into the editor box (and in which order)
• allows to guide the user by adding helpful hints what he is supposed to write

[kepper]

I wouldn't remove the current xpath setup, I would just add the RNG to get rid of pure structural checks (make sure that staffDef is nested inside staffGrp is nested inside scoreDef). If that's helpful for a given tutorial, there could still be such xpath rules to guide the user as you just said, but in most cases, they would only be necessary to check if the user's encoding goes in the right direction. So RNG should not replace XPath, but join it.

[musicEnfanthen]

Validating against RelaxNG on the client as mentioned by you and @lpugin would be great. As you said, it could reduce the sheer amount of rules to write.

Totally agree with you to see it not as alternative but joined options that would give the possibility and flexibility to use both of it (according to the specific situation). [Surely it should be RNG validated at the latest right before Verovio tries to render.]

[musicEnfanthen]

From a didactic and pedagogical perspective regarding the user, I really like the approach of xpath rules. Regarding tutorial authors, this is not very "authorfriendly".

The question that comes to my mind is: Can we keep such a granular control over the single encoding steps and simplify the rules part at the same time?

An option could be to "automatically" generate the xpath rules for the tutorial authors who can instead write predefined "self-explaining" functions. Thinking of something like:

countElement(scoreDef, 1)
countAttributes(note, *, 3)
checkForElementChild([scoreDef, staffGrp])
checkForAttributeValue(measure, n, 23)

(I played this through for one of the longer march tutorial steps and it turned out that there aren't any checks, at least at the moment, that could not be generated by the use of 4 or 5 such predefined functions)

Of course, anyone who wants to write pure xpath rules should not be prevented from doing so. But to have additionally some autogenerated standard functions could help to reduce the obstacles for people not in a massively deep relationship with XPath ;)

What do you think?

[kepper]

I like it, but I can already hear @lpugin complaining about an over-engineered solution ;-) Another idea I had was to somehow parse the sample solution in the XML files and create some kind of validation for the user input out of that. Besides all questions about the technical procedure for that, this approach seems to more complicated when it comes to giving human-readable hints on what is wrong. We surely don't want to write a complete validation engine by ourselves ;-)

[lpugin]

I am not saying anything... However, we should not loose focus indeed. I can understand that writing the rules is time consuming, but I assume it would remain quite time consuming to write the pseudo-rules once the translation infrastructure is in place. But of course I do not want to through water on the fire and all this tutorial developments are great!

[lpugin]

On the side of the RelaxNG schema side, one advantage is that it provides auto-completion. This is quite helpful, however it is also a double edged sword at the tutorial level because it shows the all list of options, which as we know can be quite long in MEI.

[kepper]

But you're using CodeMirror, right? Right now, the tutorials are built around Ace. How strong is your setup tied to CodeMirror, and do you think we could (more or less) easily achieve the same with Ace?

[lpugin]

@kepper yes. Basically the main features used are asynchronous validation and autocomplete. I could not get the autocomplete for XML working with Ace, which is the reason I tried CodeMirror (https://codemirror.net/demo/xmlcomplete.html). I assume it must be possible to have the same with Ace but I am not sure how much work this is. Do you have an example? Oppositely, what is the benefit to stick with Ace? What specific features are used in the tutorials?

[kepper]

The reason to use Ace in the first place was mostly that I'm familiar with that already. I remember having tried CodeMirror a couple of years ago, where I ran into restrictions (but I don't remember whether these restrictions were on CodeMirror or my skills…). It's definitely possible to do auto-completion in Ace as well, but I have no experience with that. We may have to build some "bridge" between the RNG and the autocompletion code – but I guess you had to do the same for CodeMirror, right? At this point, I wonder which way requires more work – switching to CodeMirror, and enabling autocompletion in Ace. Since you already said that autocompletion might contradict pedagogical concepts, I'm inclined to ignore that for now and stick with Ace…

[lpugin]

I'm inclined to ignore that for now and stick with Ace…

Sounds good.

[musicEnfanthen]

Leaving this open for now as this is still open to discussion.

To keep in mind: For some more complex tutorials, it could be interesting to think about embedding a Verovio-App or Verovio-Editor module.

[ahankinson]

Verovio editor for tutorials would be great.

[lpugin]

It would be possible to pass files to fill or to correct: https://www.verovio.org/editor/?file=/examples/hello-world/single-note.mei It should be no problem to embed