Tutorials: Final steps of march tutorial #57
Conversation
musicEnfanthen
requested review from
kepper,
soniawronkowska and
margrethesb
_tutorials/102_march/102_March.md
Outdated
|  | ||
|
|
||
| By the way: this is the beginning of _Hallingdal Bataljons Marsch_, the Opus 1 of the norwegian composer [Johan Halvorsen](https://de.wikipedia.org/wiki/Johan_Halvorsen) (1864–1935). |
_tutorials/102_march/102_march.json
Outdated
| {"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": "count(//mei:staffDef/@*) = 0", "renderanyway": false, "hint": "You need no attribute on the staffDef element."}, |
There was a problem hiding this comment.
"You need no..." -> "You do not need an..."
|
|
||
| <p>To group notes under a beam within a measure, the <code><beam></code> element is to be used. The <code><beam></code> element is a container for a series of explicitly beamed events that begins and ends entirely within a measure.</p> | ||
|
|
||
| <p id="tutorialTask">In the editor below, please add a <code><beam></code> element at the specified position before adding the two child <code><note></code>'s separately (e flat and g).</p> |
There was a problem hiding this comment.
No apostrophe after note ("notes" not "note's")
| <div> | ||
| <p id="tutorialGoal">In this step you will learn to encode dotted durations.</p> | ||
|
|
||
| <p>To encode a dotted rhythm, you need to use a <code>@dots</code> attribute on <code><note></code> element and set the number of dots as the attribute's value, e.g. <code>“1”</code> or <code>“2”</code>.</p> |
| @@ -0,0 +1,7 @@ | |||
| <div> | |||
| <p id="tutorialGoal">In this step you will learn to encode dotted durations.</p> | |||
There was a problem hiding this comment.
"You will learn how to encode..."
| @@ -0,0 +1,23 @@ | |||
| <div> | |||
| <p id="tutorialGoal">Well done, you'are almost there. In this step, you will add the last missing detail of the example: the slur in the third measure.</p> | |||
| <div> | ||
| <p id="tutorialGoal">Well done, you'are almost there. In this step, you will add the last missing detail of the example: the slur in the third measure.</p> | ||
|
|
||
| <p>There are two different ways, to encode a slur in MEI:</p> |
There was a problem hiding this comment.
no comma between 'ways' and 'to'
| <li>You can use a separate <code><slur></code> element.</li> | ||
| </ol> | ||
|
|
||
| <p>In this tutorial step, you will use the second approach: Like dynamics, <code><slur></code> elements are control events, too, what means, that they are not encoded as child elements of the corresponding events they are meant to control but in most cases outside the <code>staff</code> elements.</p> |
There was a problem hiding this comment.
This sentence should be broken into two sentences. "...elements are control events. They are not encoded..."
|
|
||
| <p>In this tutorial step, you will use the second approach: Like dynamics, <code><slur></code> elements are control events, too, what means, that they are not encoded as child elements of the corresponding events they are meant to control but in most cases outside the <code>staff</code> elements.</p> | ||
|
|
||
| <p>To indicate the starting point and end point of the slur, it is possible to apply a reference to the corresponding <code>@xml:id</code> of a <code><note></code> or <code><chord></code> element. <code>@xml:id</code>'s are identifiers with an arbitrary but unique character sequence that regularize the naming of an element throughout a document and thus facilitate building links between elements and other resources. For <code><slur></code>s, a reference to the <code>@xml:id</code> of an element can be given via the attributes <code>@startid</code> and <code>@endid</code>.</p> |
There was a problem hiding this comment.
No apostrophe-s after 'xml:id'
|
|
||
| <p>To indicate the starting point and end point of the slur, it is possible to apply a reference to the corresponding <code>@xml:id</code> of a <code><note></code> or <code><chord></code> element. <code>@xml:id</code>'s are identifiers with an arbitrary but unique character sequence that regularize the naming of an element throughout a document and thus facilitate building links between elements and other resources. For <code><slur></code>s, a reference to the <code>@xml:id</code> of an element can be given via the attributes <code>@startid</code> and <code>@endid</code>.</p> | ||
|
|
||
| <p>Along with <code>@startid</code> and <code>@endid</code>, you are supposed to use the following attributes in this step:</p> |
There was a problem hiding this comment.
"are supposed to" -> "should"
musicEnfanthen
force-pushed
the
tutorials
branch
from
fd22c7b to
abe8a8b
Compare
|
@ahankinson Many thanks for your thorough eye and review. Applied all your change requests and fixed the tutorial task for step 9 that turned out to be a copy & paste error. |
|
Do you think this is ready to merge? Any other reviewers want to chime in? |
…github.io into tutorials
…github.io into tutorials
|
Just let's wait a little so that the other requested reviewers have time to take a look. But feel free to approve (or deny) the latest changes I made after your review meanwhile. ;) The latest two commits this morning are just updating the PR with the reverted commit on tutorial branch. |
There was a problem hiding this comment.
I haven't made my way through all the steps yet. I still find this example quite "extreme" – it really goes beyond everything that I had in mind with this technical setup. That's not necessarily negative, but I'm a little distracted by the sheer amount of information. At step 2, my first reaction was to ask to split this up into two steps. Then I saw the list of steps at the bottom, which is already huge. Before making a statement about the content of this tutorial, I would like to implement the changes to the editor and preview areas that we discussed on Slack. The presentation has greatly improved with your changes already, but maybe this could help some more.
|
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… |
|
Yes: https://jsfiddle.net/lpugin/rmc18zkw/17/ |
|
Thanks for all your feedback. You adressed a lot of different issues that are very important. But as this PR is only about the content of march tutorial, I suggest to keep things separated to not overload this PR with different issues. So let's discuss the visual appearance of the editor window in #64 and about simplifying file validation in #65 (I'll be happy to refactor/adapt it for the march tutorial in another PR if necessary). @kepper I really understand your concern about this tutorial being "extreme" but I'd like to understand this rather as a compliment and as proof of concept. ;) It even works for a quite elaborated example. Of course, this tutorial is not intended (and never was) to be the first one that a real absolute beginner is supposed to be confronted with. It is rather for "advanced beginners" that have gone through different simpler tutorials which adress the different topics of the march tutorial in separate "single topic" lectures. I would imagine to have links to these "single topic" tutorials from the different steps of the march tutorial (How to write a note, How to write a beam, How to encode scoreDef?). The good thing about having the "extreme", or extended" tutorial first, is that we now can just break it down into smaller learning chunks, using a lot of the already existing code or descriptions. I will be happy to work on these, if you agree that this could be a way to go. @margrethesb told me that she can have a look at this PR in the next days. So I would like to give her a chance to give some feedback before merging this PR. Would that be OK with everyone? |
|
I didn't want to complain about the tutorial, and I think the "extreme-ness" has the benefit that we spot problems and limitations in the technical setup right away, and not in one or two years time, when someone would come up with such an example. So it helps to make our tutorial technology future-proof, which, of course, is a good thing. I also like the content. All I tried to say is that it reveals certain aspects that we need address, and where we may have to reconsider some parts of the current setup – which we already did, and where probably no one would complain. Initially, I was hoping to get the first tutorial(s) out by the end of the year, but now I think we should take some more time to do it properly ;-) I think this sounds like a nice contribution to MEC, doesn't it? Anyone out there who wants to join @musicEnfanthen (whom I've already asked) and me? With that additional time, I think you're absolutely right to wait for feedback from @margrethesb and others. As you said, we can separate out other issues and discuss them elsewhere… |
|
Sorry for my late reply, GitHub decided to deny my existence for a few days... Anyway, here goes:
|
|
Thanks @margrethesb . If I understand correctly, this PR is ready to be merged now, and further work has to (and will) be done in other PR's. So anyone with a license to merge is welcome to do so :) |
|
Thank you everyone! This is fantastic. Once we kick the tires and make sure it all works, an e-mail message to MEI-L from the 'tutorials group' would be brilliant. I think this also illustrates the value of having a work-focused meeting in the Autumn to help move community initiatives forward. Once again, bravo @musicEnfanthen, @margrethesb and @soniawronkowska . |
Thanks, but not to forget mastermind @kepper who, beside everything else, provided idea and programmatical logic for all of this. Thanks a lot! |
|
As already mentioned in my comment to #66, tutorials are not ready to be included on |
Tutorials: Final steps of march tutorial
This PR goes on tutorial branch and is ready to review.
Please do not simply merge, but let's use this PR to improve it further together.
The PR provides the basic structure with all needed files, steps, instructions and xpath rules for the advanced tutorial (march) developed at #MEIOx . It also moves the individual steps into separate subfolders for a more readable structure. It does not change the main logic (tutorials.js), view (tutorials.html) or style (CSS) in regard of @kepper working on it at the moment.
It certainly still needs the proofreading of a native speaker (would you like to have a look @siennamw ? Everyone else is invited to take a look at it, too.)
@soniawronkowska @margrethesb could you please have a look especially at the proposed
"...-desc.html"files here where all the instructions are included and give your feedback here via GitHub's review function? I had to stretch the tutorial to 12 steps in favor of having a better distinction of several issues.@kepper could you (beside everythig else ;)) have a closer look at the xpath rules provided and the correctness of the content information in the instructions?
Looking forward to your feedback.