Close
MerMEId

Frequently Asked Questions (FAQ)

Installation and access

HTML preview and presentation of data

Using the editor

Customizing the MerMEId editor

Publishing

Contact

Installation and access

Can I install MerMEId on my laptop?

In principle, yes. Please note, however, that MerMEId is a web application, not a desktop application. You will need to have Docker installed on your machine to run the MerMEId container. Extra care needs to be taken to persist the data within the running container, otherwise you'll loose everything you entered. See the Readme, especially the section "How to use this Docker image".

Can I use The Edirom MerMEId server for our project?

Unfortunately no. The demo installation at mermeid.edirom.de is meant for demonstration only. The library cannot host other projects' data. You are welcome, on the other hand, to use the demo installation to try out MerMEId or even to do preliminary work until you have set up your own server. Note, however, that the library does not take any responsibility for any loss of data stored on the demo server. The data at the demo server are freely accessible for anyone to edit or even delete. If you are doing any serious work there, make sure to make local copies of your data frequently (See: How do I copy or move my data from one MerMEId instance to another?). Furthermore, the MerMEId demo instance is redeployed with every commit to the development branch, resulting in frequent wiping of its data.

How many MerMEId installations do I need for my project?

Preferably only one. MerMEId is a web application (See: Can I install MerMEId on my laptop?), and your data will need to be stored on the same server. If you have more than one installation, you will have trouble synchronizing your data across MerMEId intances (probably by copying files back and forth manually).

How do I copy or move my data from one MerMEId instance to another?

To move or copy XML data files from one MerMEId installation to another, download your files to your hard drive first. You can do so one file at a time by right-clicking (on Windows machines) the file's XML icon in the file list and selecting "Save as..." or equivalent. If you need to download many files it will probably be easier to use the eXist database's admin client. You will need to have administrator access to the database in order to use it. You will probably find the adminstration page at http://[yourservername.yourdomain]:8080/exist/. Click the 'Collections' option to open the database's file manager which allows you to download all or some of your files. You will find your files in the 'dcm' folder. Use the same component on another server to upload your data (again, to the 'dcm' folder).

What if some day MerMEId is no longer maintained? Will I lose my data?

No. One of the core ideas of MerMEId is that it produces data compliant to the MEI XML schema – an open, well-documented standard for encoding musical information. Basically, MerMEId is simply a user interface to allow you to produce MEI XML without having to hand-code everything. You can use other tools such as a generic XML editor to do the same, just in a less convenient way. So even without MerMEId, you can still have valid MEI XML data and continue your work using other tools. Just make sure always to keep a copy of your data somewhere safe.

How do I know which MerMEId version is running on my server?

To see the version (revision) number of your installation, open any file in the editor (or create a new one) and click the MerMEId logo logo in the lower right corner.

HTML preview and presentation of data

Can I change the way MerMEId displays my data?

Yes, you can. MerMEId's basic MEI-to-HTML XSL style sheet, mei_to_html.xsl, is located in the eXist database (in db/style/). By modifying it you may alter the way MerMEId displays your data, or you can make a copy of it to use for your presentation outside of MerMEId. You may also want to download and/or alter the corresponding CSS style sheet, mei_to_html.css, found in the same location.
If you want to switch between different transformations, you can place custom XSL style sheets in the eXist database (in db/style/) and tell MerMEId which transformation to use by adding a parameter ?xsl=[your xsl file name] to the preview URL, like: http://www.example.com/storage/present.xq?xsl=your_style_sheet.xsl
Even though MerMEId can produce HTML to display your data (either by clicking a work's title in the file list or by clicking the 'View as HTML' icon in the editor), MerMEId does not tell you how to present your data to the public or in any other context. The built-in HTML preview is meant for reviewing your data for convenient proofreading etc.
You are welcome to re-use or alter the XSL style sheet used to create the preview for your public presentation, but more likely you will want to define your own. There is no forced connection between the way MerMEIds displays your data and the way your final presentation does. In the public version of the Catalogue of Carl Nielsen's Works (CNW), we are using a slightly modified version of MerMEId's HTML preview XSL style sheet to do the basic formatting; we have basically just filtered out certain information and linked to a different CSS style sheet.

Can I change the language of the HTML output?

MerMEId adds a number of pre-defined labels and phrases (such as 'Performances', 'Sources' etc.) when generating the HTML page. By default, these are in English. You may temporarily override the default by adding &language=[language identifier] to the URL of the HTML preview – for instance, http://labs.kb.dk/storage/present.xq?doc=nielsen_cnw0130.xml&language=de.
Of course changing the language does not affect any text you have entered in the editor. You can permanently change the HTML view's default language by editing the default_language variable at the beginning of the mei_to_html.xsl file located in eXist (in the db/style/ folder). MerMEId currently comes with English (en), German (de) and Danish (da) translations. These are stored in the db/style/language/ folder in eXist.

MerMEId does not show some information I have entered. Why?

The built-in HTML preview is designed to display all the information you may enter in the editor, with a few exceptions. Some information is very complex to handle; for instance, only some of the possible relations between sources, versions etc. are pre-defined to have a visible effect in the HTML preview. If you want other relations to have a an effect, you will have to define it in your presentation. Finally, there is definitely a chance that we have simply forgotten to implement a certain feature in the HTML preview because we haven't used it yet. Please let us know if something is missing.

Will MerMEId render any music encoded in my files?

Encoded music may appear in two different places in your MEI files: Incipits encoded in the header, and any music (score) encoded in the MEI file's main music section (the <music> element).

MerMEId comes with a demo file to illustrate different ways of including incipits. Encoded incipits are rendered using the Verovio MEI renderer.

By default, MerMEId also renders any music encoded in the main music part of the document – or at least the beginning of it. This rendering also uses Verovio. You may deactivate it temporarily by adding '&score=false' to the URL of MerMEId's HTML presentation. To turn it off permanently, change the value of the variable 'view_score' to 'false' in the the MEI-to-HTML transformation (the file mei_to_html.xsl). This reverses the behaviour: you may then activate rendering temporarily by adding the parameter '&score=true' to the URL.

Using the editor

How do I start a new file collection or catalogue?

You may have noticed the use of 'Collection' names in MerMEId's file list, for instance, 'MerMEId Demo'. The collection names are intended to enable you to distinguish or select files belonging to a certain catalogue in your database. This makes it possible to have any number of catalogues in the same database. To make your file part of a specific catalogue or collection, open the file in the editor, go to the 'File' tab, and enter the collection name in the field labeled 'File Collection' under 'Series' (and save your work, of course). In the file list, you will now see the collection name in the 'Collection' column, and it will also appear in the collection drop-down list, allowing you to search for files in that collection only.

How do I make MerMEId recognize a certain number as a catalogue work number?

You may have noticed that the demo files in MerMEId's file list are labeled like'MerMEId Demo 3' in the 'Collection' column. To make MerMEId recognize a number as the work's or file's number in your collection (equivalent to the numbers in the BWV, for instance), go to the 'Work' tab, add a work identifier (under 'Identifier'), enter the file collection's name as the list name and the desired number in the 'No.' field. If MerMEId finds a work identifier corresponding to the file collection defined at the 'File' tab, it regards the identifier's number as the catalogue number.

Can I paste any HTML tag/structure into the TINYMCE editor?

No, since the HTML input needs to be transformed to MEI in the backend, only a limited set of HTML tags are supported. These include the tags that are accesible via the buttons of the editor like <em>, <span>, or <strong>. Other HTML markup will be silently removed.

Customizing the MerMEId editor

Can I add fields to the editor form or alter existing ones?

In principle yes, if you know how to write Orbeon XForms. You will find the MerMEId source code at GitHub. You are free to change it to make your customized version of MerMEId. However, note that this will require you to make the same changes again after installing one of our MerMEId updates. Also, MerMEId is based on sharing. No one else will benefit from your changes if you keep them for yourself. Therefore we would like to encourage you to share your improvements either by forking the code at GitHub and submitting a pull request or to discuss your wishes with us; if we agree that the changes will be of general interest, we may be willing to implement them if we have the time. Another possibility is to pay us (that is, the Danish Centre for Music Editing at the Royal Library) to make the desired improvements. That's a great way to support the MerMEId project.

I don't want MerMEId to create change log entries automatically. Can I turn it off?

In MerMEId's configuration file mermeid_configuration.xml there's an option to turn off the automatic logging of changes.
This is also where you can entirely deactivate advanced features such as the attribute editor and the code inspector.

Can I change the pre-defined instrument names and codes?

Yes. If you only want to change the displayed instrument name in a few cases, the simplest way is to manually change the text MerMEId inserts in every instance. The more efficient way – and the only way, if you also want to change the available standard code values – is to change the lists of instrument and ensemble names kept in the eXist database. They are located in a folder named library together with other customizable lists. The instrument and ensemble names are stored in three separate files:

The file instrument_groups.xml is the one populating the menu popping up when clicking an "Add ensemble" button; it is intended to provide an easy way of entering some fairly standardized instrumentations quickly. Of course, the elements inserted from the menu can be adjusted afterwards to have the desired instrument numbers and names.
MerMEId comes with two different sets of instrument and ensemble definitions: One according to MARC and one according to UNIMARC standards. They are also located in eXist's library folder and have "_marc" and "_unimarc" added to their file names, respectively. MerMEId looks for the files without the indication of standard, i.e. instruments.xml, ensembles.xml and instrument_groups.xml, so to change from using the MARC lists (default) to using UNIMARC, simply rename the files accordingly.
If you are not familiar with eXist, ask your system administrator about how to access and edit the files.

Which standard should I use for instrument codes and names? MARC or UNIMARC? Do I have to use one?

The use pupose of using standard codes for instruments is to optimize machine-readability and data interchange. If you are not concerned about interchangeability, you do not have to use any instrument codes. In that case, simply do not choose an instrument from the standard code drop-down list (i.e., leave it blank) and enter the instrument's name in the name field.
However, we recommend referring to standard codes whenever possible. Which standard to use depends on the nature, purpose and possible uses of your data. In some cases, a very precise coding may be desirable (in that case, use UNIMARC), in other cases it is sufficient to have codes just describing the instrumentation roughly (in that case, use MARC).
MerMEId comes with two pre-defined sets lists of instruments and ensembles (see above): One containing the instruments defined as part of the MARC cataloguing standard (default), and one containing the much more detailed UNIMARC list of instruments. Which one to use is up to you.
Please note that the displayed names of the instruments and ensembles are independent of the codes used, so you can change the names to whatever you want. For instance, some would prefer using Italian terms for instruments, other would use English terms. Some prefer abbreviations, others prefer full names.
This means that your naming of instruments can be as detailed as you like, even if you choose the less detailed MARC instrument codes.

The authority file I use is not listed. Can I add it?

Yes. You can edit the list the same way you would change pre-defined instruments names. Look for the file authority_files.xml in the library folder.

How do I make MerMEId recognize other abbreviations?

The same way you would change pre-defined instruments names. Look for the file abbreviations.xml in the library folder.

How do I change the genre keywords in the 'Keywords' menu?

The same way you would change pre-defined instruments names. The keyword file (keywords.xml) is located in the library folder. It has two sections: first, a list of hierarchically ordered keywords (called 'level 1' and 'level 2' terms); second, a list of unordered supplementary keywords. The two-level ordered list of genre terms is useful if you intend to order your files by genre at some point or enable users to browse your catalogue by genre. That's how we generated the genre menu in the CNW.

What else can I customize?

Various lists of pre-defined values are placed in the library folder of the eXist database to make them easily customizable. Apart from those mentioned above, the lists include:

See also:
Can I change the language of the HTML output?
I don't want MerMEId to create change log entries automatically. Can I turn it off?

Publishing

I would like to make a web catalog like the CNW. Is the user interface included in MerMEId?

No. MerMEId is a tool for creating and editing the XML data for a catalogue of works or sources, not a presentation tool. We're quite sure that every project will want to have their data presented in their own way, so we haven't made our presentation part of MerMEId. To create the public CNW catalogue, we basically use MerMEId's MEI-to-HTML transformation, and add a few exceptions and alterations on top of it. We have added a few XQuery files for the search facilities and a couple of flat HTML files for the text-only pages. A few more XQuery scripts wrap the pages with a header and a footer. The code is available as a separate project at GitHub.

Contact

How do I stay informed about changes and updates?

We recommend that you sign up for the Music Encoding Slack where we host a dedicated #mermeid channel. Additionally, you can keep an eye on our GitHub space at github.com/Edirom/MerMEId where all the issues, milestones and releases are kept.