Git Product home page Git Product logo

guidelines's Introduction

The Music Encoding Initiative

DOI GitHub release (with filter) GitHub Deploy Schema and Guidelines

The Music Encoding Initiative (MEI) is an open-source effort to define a system for encoding musical documents in a machine-readable structure. MEI brings together specialists from various music research communities, including technologists, librarians, historians, and theorists in a common effort to define best practices for representing a broad range of musical documents and structures. The results of these discussions are formalized in the MEI Source and customizations, a core set of rules for recording physical and intellectual characteristics of music notation documents expressed in TEI’s ODD language (One Document Does-it-all, cf. amongst others: Viglianti, 2019). As such, the MEI Source contains both, the specifications that can be compiled to schema formats for validating XML files, and documentation in prose, the MEI Guidelines, which provide detailed explanations of the components of the MEI model and best practices suggestions.

The MEI Source is not a schema in itself; rather, it can be used to build customized schemas, such as mei-CMN, mei-Mensural, mei-all, etc. (also see Customizing MEI). This repository already includes several customizations. While these can form an ideal starting point for creating your own customizations, you should also understand customization and building processes.

In this document, you will learn how to contribute to the development of MEI by building the schema and guidelines (you should also consider consulting the tutorial on "Understanding ODD"). For the pre-built schemas of the latest release of MEI, please consult the "schemas" section of the music-encoding website.

Structure of this repository

This repository contains all the source code of the MEI Schema and Guidelines:

  • .github: Configuration files for GitHub Actions workflows.
  • customizations: TEI ODD files that allow you to build customized MEI schemata.
  • source: Contains the source code, as expressed in TEI ODD. This includes the source code for the MEI Guidelines and the MEI schema modules.
  • submodules: A container for Git Submodules: third-party developments that are needed, e.g., for building this repository's contents, but which are not part of our codebase.
  • tests: Unit tests for the MEI Schemata.
  • utils: Helper scripts e.g. for compiling schemata and guidelines from this repository.

Important

For the sake of the continuous integration (CI) workflow, the build artifacts of the schemata and guidelines are no longer included in this repository, but are generated on every commit to the develop branch and automatically pushed to their dedicated repositories. For more information please see the section Additional Resources below.

Nevertheless, it is possible to build any customization locally in your working copy of this repository.

Validating MEI files against an MEI Schema

One of the core strengths of the MEI Schema is that it allows an individual to validate an MEI file against an XML Schema to ensure the MEI file conforms to expected encodings and behaviors. To validate an MEI file you need an XML validation engine. XML Authoring tools, such as oXygen, might have built-in validation tools. There are also several command line utilities, including xmllint and jing.

For example, you might validate an MEI file from the sample-encodings project using the xmllint command line tool:

xmllint --noout --relaxng schemata/mei-CMN.rng "sample-encodings/MEI 3.0/Music/Complete\ examples/Bach_Ein_festeBurg.mei"

Or, the same command using jing.

jing schemata/mei-CMN.rng "sample-encodings/MEI 3.0/Music/Complete\ examples/Bach_Ein_festeBurg.mei"

Customizing MEI

The MEI model may be customized to express and validate different types of music documents. Customizations are configured with individual ODD files. This repository already includes several customizations:

  • mei-CMN: Validates MEI files that express common Western music notation.
  • mei-Mensural: Validates MEI files that express white Mensural notation (will raise validation errors if elements like "measure" exist in the MEI encoding).
  • mei-Neumes: Validates MEI files that express Neume notation (like Mensural, will raise validation errors if elements that are not part of neume notation exist in an encoding.)
  • mei-all: The full MEI Schema. This is the most permissive customization of MEI.
  • mei-all_anyStart: A customization of mei-all, allowing every MEI element as the root element.
  • mei-basic: The purpose of mei-Basic is to serve as common ground for data interchange, both between projects using different profiles of MEI, and other encoding schemes

Why Customizations?

For those who are used to having a single DTD or W3C Schema to validate music notation encodings, the customization process may seem to be a complex way of arriving at a schema to validate music notation. However, customizations are a vital part of the expressive power of MEI, and when used to their full extent, can assist organizations in ensuring the integrity and validity of their data.

When designing a music encoding system there are many contradictory and non-standardized practices associated with writing music notation. Different repertoires may have extremely different ways of expressing pitch or rhythm; for example, rhythm in Mensural notation is incompatible with the later systems developed in common Western notation.

Most attempts at addressing this complexity restrict a schema to only a certain subset of music notation and do not attempt to accurately represent the semantics of music notation that falls outside of its defined scope. So, for example, a system designed for common Western notation that depends on the existence of measures, duration, note shapes, or even staves, cannot semantically represent notations that do not have these features.

The MEI takes a different approach. With the customization system, schemas may be generated from an existing ‘library’ of well-defined musical behaviors, but each behavior may be mixed and matched according to the needs of the notation. In this sense, the MEI source functions more as a ‘library’ of music encoding tools by which many different types of notation can be expressed and not just a single monolithic schema.

Building MEI

The build process of MEI can produce several artifacts, as listed below. Depending on what artifacts you want to build, the build system has to meet additional requirements.

Artifacts Technologies Tools
Compiled ODD XInclude, XSLT 3.0 Saxon HE with Xerces
Schemata XInclude, XSLT 3.0 Saxon HE with Xerces
Guidelines HTML XInclude, XSLT 3.0, MEI to SVG Saxon HE with Xerces, Verovio Toolkit
Guidelines PDF XInclude, XSLT 3.0, MEI to SVG, HTML to PDF Saxon HE with Xerces, Verovio Toolkit, Prince XML

While it is possible to build the artifacts with other tools, the above are tested and thus recommended. Moreover, we try to support the building process on the most common operating systems (Microsoft Windows, Apple macOS and Linux), and currently have the following documented ways of building the artifacts:

  • command line: If your build system meets the prerequisites as described in Building MEI on the command line, you can build the artifacts natively.
  • Docker: MEI maintains a Docker image that meets all the prerequisites and can be used for building the artifacts via the command line. How to use the Docker image is described in the README of the docker-mei repository.
  • oXygen XML Editor: When the command line is not your preferred tool and you do not want to build the Guidelines PDF, you might consider using alternative environments, such as Synchrosoft’s oXygen XML software family. A description of how to set up corresponding transformation scenarios can be found in Building MEI with oXygen XML Editor.

Additional Resources

A live version of the MEI Guidelines is available on the MEI Website in the ’Documentation‘ menu:

In addition to the source files for MEI in this repository, there are other useful resources in other MEI repositories. The prebuilt release and development versions of:

And moreover

Referenced Material

  • Viglianti, R. (2019). One Document Does-it-all (ODD): A language for documentation, schema generation, and customization from the Text Encoding Initiative. Symposium on Markup Vocabulary Customization, Washington, DC. https://doi.org/10.4242/BalisageVol24.Viglianti01

License

Copyright 2017-2023 by the Music Encoding Initiative (MEI) Board (formerly known as "MEI Council")

Licensed under the Educational Community License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://opensource.org/licenses/ECL-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

This is a derivative work based on earlier versions of the schema © 2001-2006 Perry Roland and the Rector and Visitors of the University of Virginia; licensed under the Educational Community License version 1.0.

CONTACT: [email protected]

guidelines's People

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

guidelines's Issues

Color for element list boxes and attribute zebra-striping

In the list of elements:
http://music-encoding.org/guidelines/v3/elements.html

screen shot 2018-06-07 at 11 53 45 pm

And on element documentation pages:
http://music-encoding.org/guidelines/v3/elements/desc.html

The alternating gray background and element tag backgrounds in the element lists are too dark to the point of being distracting and reducing the readability of the text.

It would be useful for the gray of such regions match that of the ODD sample code at the bottom of the element reference pages:

screen shot 2018-06-07 at 11 49 36 pm

The gray color is currently #e5e5e5, but should be lightened to #f5f5f5.

Add anchors to specific attributes in elements

For example, it would be nice to link to the @enclose attribute on <accid>. There are likely two parts to this -- 1: including an id on the HTML element (id="accid-att-enclose") and 2: Adding a small <a href="#accid-att-enclose">(some fancy icon symbol here)</a> to let people access the link.

Guidelines text is cramped

There's a lot of white space in the guidelines docs. I propose changing it to fill more of the screen.

Also, the striped 'table' of attributes changes background on hover, which is strange.

I can fix this if that's ok?

Old vs. new guideline system

I'm certain there are good reasons for maintaining the guidelines as Markdown for Github pages instead of TEI, but those reasons are not apparent to me at the moment and I must confess, I just got frustrated with understanding what's going on while trying to create an admittedly quick pull request on a really late Sunday evening. At the same time I feel really bad about this because I got upset with something I know you guys are investing a lot of time and thought. So please, can you enlighten me?

Here's my rant about things I got frustrated with. If those things are just preliminary because the transition is still work in progress, I apologize - please ignore them in that case. I already anticipate being much less cranky tomorrow morning, but then I'll be occupied with other stuff and this feedback wouldn't be written at all. So enjoy:

Cryptic noise

Now we have

{% include specDesc.html version=page.version elem="itemList" atts="" %}
{% include specDesc.html version=page.version elem="componentGrp" atts="" %}
{% include specDesc.html version=page.version elem="relationList" atts="" %}

where we previously had

<specList>
  <specDesc key="itemList"/>
  <specDesc key="componentGrp"/>
  <specDesc key="relationList"/>
</specList>

And we have

[source]({{ site.baseurl }}/{{ page.version }}/elements/source.html){:.link_odd_elementSpec}

where we used to have

<gi scheme="MEI">source</gi>

oXygen used to help us very nicely with the XML noise - what's going to help us with the awkward boilerplate noise we have to add for all these new things now? I fear guideline writers will just not link to elements and attributes anymore because it's just too much hassle and - even worse - makes the text utterly unreadable. Honestly, who can read something like this?

The content model of the [source]({{ site.baseurl }}/{{ page.version }}/elements/source.html){:.link_odd_elementSpec} element is similar to that of the [fileDesc]({{ site.baseurl }}/{{ page.version }}/elements/fileDesc.html){:.link_odd_elementSpec} and [work]({{ site.baseurl }}/{{ page.version }}/elements/work.html){:.link_odd_elementSpec} elements. The list below
reflects the order in which the optional components of [source]({{ site.baseurl }}/{{ page.version }}/elements/source.html){:.link_odd_elementSpec} must
occur.

Technically, that's a signal to noise ratio of 0.5. We used to have a ratio of 1.9:

<p>The content model of the <gi scheme="MEI">source</gi> element is similar to that of the <gi
scheme="MEI">fileDesc</gi> and <gi scheme="MEI">work</gi> elements. The list below
reflects the order in which the optional components of <gi scheme="MEI">source</gi> must
occur.</p>

How do we make sure we didn't make a typo anywhere in that boilerplate jungle? And how will this be maintained if there needs to be a change in the boilerplate code that's repeated hundreds of times?

I mean, the reason why markdown exists is because it's simpler and less noisy than HTML. Where a Markdown based solution makes things more complicated than with XML - why do we use Markdown instead of XML in the first place? If it's because it's beneficial to move to Github pages, wouldn't it be possible to generate those from TEI?

Examples in separate files

Examples are an essential part of the guidelines and closely tied to the text. 20% of our examples are one-liners. Can't we keep those together? When editing the guidelines, we must be able to read them in a sensible form.

At least for me, it's harder to make sense of the documentation in markdown form when I don't see the examples (or have to open them one-by-one when reading through while editing).

Linking and TOC related stuff

It seems that chapters need to be numbered manually. Not so convenient, but what's worse, do we have to state the chapter titles (and potentially numbers) explictly everywhere we link to them - and whenever a title changes, we have to change every link caption if we don't want to become inconsistent? Also, this is once more an extreme case of boilerplate overkill:

<ptr target="#headerFileDescription"/>

vs.

<a class="link_ptr" title="File Description" href="{{ site.baseurl }}/{{ page.version }}/guidelines/header.html#headerFileDescription">2.1 File Description</a>

Separation of schema and guidelines

This is just a minor point, but while I'm in full ranting flow: I feel that it makes sense to discuss and perform changes to schema and guidelines in synch. Therefore I don't really see where it helps to have separate repos and issue trackers for them.

Wrap-up

I got the impression, writing guidelines is made much harder rather than simpler. This is unfortunate because it's clear we need more and better documentation. People who are already involved in writing documentation will achieve less if it's made harder. And new editors will more likely be repelled rather than encouraged. All potential guideline editors feel at home with XML and oXygen. Why force them into this new system?

Can you explain the motivation? Is what I criticize going to change?

Revise CMN section

Labelling staves has changed in MEI4.
References to @label and @label.abbr should be updated.

ordered lists

at the moment ordered list do not get an index number output before each list item

assign @bwbohl

implicit mensur

The section 5.2. Mensuration Signs is not totally clear on how the information given should be rendered, and I'd like to improve it.
Q: Do @modusmaior, @modusminor, @tempus and @prolatio imply a sign to be rendered, or are they meant to just carry musical meaning, i.e. do one always have to give explicit information about the desired sign to be rendered by @sign, @orient, @slash, and @dot?

branching model

Dear all,

I just was about to start working on some guidelines issues and stumbled over the current branch situation. Apparently "master" is where the development happens and the other branches "develop", "feature-travis" and "feature-gemfile" are somewhat stale and behind at least by 85 commits.
Nevertheless the naming scheme of the branches as the presence of both "master" and "develop" suggest a "gitflow" approach.

Can we agree on gitflow? I.e. the "master" branch being for tagged releases (maybe only PR-able by others) "develop" as main area for (as the name suggests ;-) development and use feature, release and hot fix branches as e.g. introduced by Vincent Driessen in his post «A successful Git branching model» at http://nvie.com/posts/a-successful-git-branching-model/?

I'd very much appreciate that!

Of course this should be documented in the README's section on contributing, but that's another issue.

Facet letter de-emphasis on elements page

It would be useful to de-emphasize the facet letters ("a", "b, "c", etc.) on the elements list:

https://music-encoding.org/guidelines/v4/elements.html

Current styling:

screen shot 2019-01-02 at 4 17 16 pm

Proposed styling:

screen shot 2019-01-02 at 4 17 54 pm

This would apply to other pages as well, such as:

https://music-encoding.org/guidelines/v4/attribute-classes.html

Also notice the letters are centered horizontally in the space which make it easier to read the list. Perhaps also center them vertical in the space between the lines, but I did not see an easy way of doing that for a test.

jQuery that changed the style:

$("div.label").css("text-align", "center").css("color", "#ccc")

maybe for site-wide styling, it would be something like:

div.facet.letter.overview div.label {
    text-align: center;
   color: \#ccc;
}

classBox missing borders

The classBox in data-types has no borders on the right and at the bottom.
Is this intentional, or missing in CSS?

Link to triggering commit

It would be useful to have in the dev version of the guidelines a link to the music-encoding/music-encoding repo that triggered the corresponding build. Maybe we can have this in the footer?

Clarify use of @dur.ges

data.DURATION.gestural and data.DURATION both refer to data.DURATION.cmn (and data.DURATION.mensural). That restricts the values of @dur.ges to the same as those for @dur, which doesn't make sense, does it?

tables in markdown

the current files have a html table in the markdown files is this a workaround that should be fixed to output something else (more markdownish) or do we stick to it?

shall we split up macro groups from data types?

Right now, we mix data types (encoded as <tei:macroSpec type="dt">) and "macro groups" (encoded as <tei:macroSpec type="pe">) into one category in our specs:

https://music-encoding.org/guidelines/v4/data-types.html.

However, we separate them out and place them at the bottom, under the (not particularly helpful) label "Macros". As I'm currently revising the complete spec processing, I was wondering if we should give them a separate entry in our list, even though we have only six of them. I think this would be helpful, not just because we could include some explanation on them in the overview page. Opinions, @pe-ro, @lpugin, @ahankinson, @rettinghaus, @musicEnfanthen, @margrethesb, @soniawronkowska, anyone?

[email protected] meaning

[email protected] (and [email protected]) can have the value above or below. What exactly does this mean? The documentation says that it is in relation to the noteheads:

screen shot 2018-07-22 at 11 00 06 am

@place in other cases are related to a fixed vertical orientation, such as above or below the staff. But in this case the meaning is a relative position dependent on the orientation of the notes on the staff (i.e., the stem direction). It seems that above really means stem/tail and below really means head/notehead.

Here is a diagram:

screen shot 2018-07-22 at 11 19 02 am

If you use the standard definition of above and below, these positions remain constant whether the stem is above or below the notehead.

Related to this, what is the meaning of [email protected] for stemless notes? If relative position is dependent on the stem direction, then should a stem direction be assigned to the stemless notes (I find this reasonable to do).

Adding include template for images

Currently generated as

<figure class="figure"><img src="{{ site.baseurl }}/Images/modules/cmn/grace-300.png" class="img-responsive"><figcaption class="figure-caption">Figure 2. Grace notes</figcaption>
</figure>

One question to address is figure numbering. Do we want to keep it?

Wrong use of <subst> in guidelines for <supplied>?

In my understanding, <subst> is for encoding scribal substitutions, not editorial substitutions. That's how I read the guideline chapter Substitutions, Restorations, and Handshifts, which seems to match how the TEI equivalent is designed to be used.

However, <subst> is used for grouping editorial additions in an example of chapter Omissions, Unclear Readings, Damage, and Supplied Readings. Being no edittrans expert, I feel this is probably improper use and the example should be changed - but how? <choice> wouldn't be a drop-in replacement for <subst> here, it neither allows <gap> nor <supplied> as content.

As a side note: All notes under the beam in that example are oddly encoded as quarter notes.

Namespaces in examples

Do we really want / need to have these namespaces in all examples?

xmlns="http://www.tei-c.org/ns/Examples" xmlns:rng="http://relaxng.org/ns/structure/1.0" xmlns:sch="http://purl.oclc.org/dsdl/schematron" 

backlinks from elements to guidelines

In C'ville, we discussed the potential addition of links from the elementSpecs to all chapters in which the current element is mentioned. However, this is possible only as long as we still have the guidelines in XML, and will go away soon. After that, we need to come up with a mechanism in Travis that identifies these references in the guideline markdown files and inserts that automatically in the HTML version of the elementSpecs (no need to put it in the ODD definitions). We don't have that mechanism in place yet, so there is a certain risk of not being able to reflect the current state of the guideline chapters in the elementSpecs. At the same time, the guidelines aren't moving fast these days. I'm inclined to include those references now, and come up with a maintenance plan for them based on Travis as a second step. Thoughts?

specDesc template not requiring version

We should change the specDesc template calls from

{% include specDesc.html version=page.version elem="mei" atts="" %} 

to just

{% include specDesc.html elem="mei" atts="" %} 

plainExample template not requiring version

We should change plainExample template calls from

{% include plainExample.html example="examples/shared/shared-sample014.xml" valid="true" version=page.version %}

to

{% include plainExample.html example="examples/shared/shared-sample014.xml" valid="true" %}

example glyphs missing in text

There are several glyphs in the guidelines text missing now, e.g. see MEI_Guidelines_v3.0.0.pdf p. 160 and p. 168.
How should that be addressed?

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.