Organize definitions of shared attributes

[joeberkovitz]

Various elements belonging to specific kinds of MNX content share a common set of attributes. For example, any direction element (<clef>, <expression>, ...) can have a location attribute, simply by virtue of being a kind of direction.

Currently these attributes are omitted from the spec which is being addressed by #253. This issue asks that the 1.0 spec not individually define each shared attribute for each element that has it, which would lead to duplication, definition clutter, difficult spec maintenance and failure to communicate the structure of the schema. And the number of attributes increases with the buildout of MNX, particularly w/r/t styling, managing shared attributes will become more and more important.

As one proposal, in such elements the spec could incorporate a reference to, say, direction attributes as a hyperlink to a single definition of the shared attributes. Or they could be incorporated by value (i.e. duplicated) but under a distinct subheading that also hyperlinks to an explanation of the shared concept.

[adrianholovaty]

Our docs system already has the concept of "attritbute groups." For example, we have an attribute group called "span" that's currently shared by three elements — cresc, dim and wedge — and provides an "end" attribute. This means we can indeed define them in one place and not need to worry about duplication or things getting out of sync. The MusicXML spec also uses this feature extensively.

I'd definitely recommend setting up the docs system locally and playing around, so you can see for yourself! Instructions here.

However, the user-facing end of the spec doesn't expose these attribute groups. Philosophically I've considered them to be an implementation detail that users shouldn't need to worry about. I discussed this with @mdgood when we were building out the new MusicXML docs in this system, and he agreed it would be clearer not to expose that implementation detail.

When it comes to MNX, one problem I had with the older spec is that it required too much jumping around and crossreferencing for somebody who just wanted to see the definitive list of attributes that an element has. It was borderline impenetrable for me when I was first reading it; made me feel dumb. I want the MNX docs to avoid that feeling. At some level, you shouldn't necessarily need to know what a "spanning element" is; that's best left to spec authors/contributors. I can completely appreciate that this is a difference in philosophy/usability and we might not agree on that.

I think an argument can be made to organize the list of attributes by group/theme, perhaps surfacing a label for the group name. At the moment attributes are ordered by whether they're required, then alphabetically.

[joeberkovitz]

Thanks for explaining all that. Overall I think you've made the spec much more accessible and easy to work with, and I like the overall direction you've taken.

So it sounds like the definitions (if not the presentations) are already consolidated. I think all I'm asking for is to organize the list of attributes under shared groups as you suggested, and perhaps have the label link to some text that explains what the group means since this is useful information for understanding it.

Retitling the issue for clarity.

[adrianholovaty]

"So it sounds like the definitions (if not the presentations) are already consolidated." — yes, exactly. :)

I agree that would be a nice improvement. Will add this to the to-do list... Thanks for bringing it up!

[cecilios]

I'm not sure if my post is what this issue is about. Sorry this is not the right place.

To me it is not only the issue of shared attributes but also about content origin and hierarchy.

Current specification is very practical to navigate and get the whole picture about an specific element. Therefore, when having to implement MNX it is extremely useful. I like it very much for this. And I'm in favor of the new format.

But I have doubts if very valuable information will be lost when the transition to the new format is completed. For instance, the idea of classifying directions as single-ended, spanning and liason. Or to understand that the content of an element is in fact composed by information from different origins, e.g. metadata content, interpretation content and the semantic content. All this information is important not only for having a better understanding of the reasons for some element being designed as it is, but for better understanding of the MNX hierarchy as a whole and for other purposes (academic, better understanding of the music notation).

I'm wondering if the new format will incorporate, somehow (something simple to maintain, not necessarily navigable), all this information about hierarchy and elements classification. It will be a pity that all the conceptual effort behind the current hierarchy and design could be lost.

[adrianholovaty]

@cecilios Thanks very much for those thoughts. Yes, this is exactly the right place for that feedback and you're commenting in the right place! We'll indeed find a way to incorporate that information in the new system.