Merge pull request #55 from aerhard/meta-data

Some documentation and minor restructuring

README.md

@@ -21,19 +21,23 @@ $ bower install
 
 ## Usage
 
-The library provides the function `render_notation` which takes four
+The library provides the function `render_notation` which takes up to six
 arguments:
 
- - `score` should be a markup fragment containing the MEI
+ - `xmlDoc` (XMLDocument) should be a markup fragment containing the MEI
 
- - `target` should be an HTML <canvas> element onto which the notation
+ - `target` (Element) should be an HTML <canvas> or <svg> element onto which the notation
    will be drawn
 
- - `width` should be the width of the canvas (optional)
+ - `width` (Number) should be the width of the canvas in pixels. Defaults to 800 (optional)
 
- - `height` should be the height of the canvas (optional)
+ - `height` (Number) should be the height of the canvas in pixels. Defaults to 350 (optional)
 
-For sample function calls see the test cases in the 'tests' directory! 
+ - `backend` (Vex.Flow.Renderer.Backends.CANVAS|Vex.Flow.Renderer.Backends.RAPHAEL) specifies the VexFlow backend to use. Defaults to Vex.Flow.Renderer.Backends.CANVAS (optional)
+
+ - `options` (Object) may contain additional conversion and rendering options; see the comments on the default options in `src/Converter.js` for details (optional)
+
+For sample function calls see the test runs in the 'tests' directory! 
 
 ## MeiLib.js 
 
@@ -61,7 +65,7 @@ comments within the source file meilib.js
 
 Only a small subset of MEI has so far been implemented. Many
 conventional aspects of common practice notation have been ignored
-(such as repeat accidentals, stem directions). It's also important to
+(such as repeat accidentals). It's also important to
 remember that VexFlow is a moving target, it's in constant development
 and so this code could break at any time.
 

bower.json

@@ -3,7 +3,7 @@
   "version": "0.1.0",
   "homepage": "http://tei-music-sig.github.io/MEItoVexFlow/",
   "authors": [
-    "irochicken raffazizzi zolaemil aerhard"
+    "ironchicken raffazizzi zolaemil aerhard"
   ],
   "description": "MEI to VexFlow bridge library",
   "main": "meitovexflow.js",
@@ -17,9 +17,7 @@
   "ignore": [
     "**/.*",
     "node_modules",
-    "bower_components",
-    "test",
-    "tests"
+    "bower_components"
   ],
   "dependencies": {
     "jquery": "~2.1.0",

src/Converter.js

@@ -1046,9 +1046,9 @@ var MEI2VF = ( function(m2v, MeiLib, VF, $, undefined) {
        * @method processChord
        */
       processChord : function(element, staff, staff_n) {
-        var me = this, i, j, hasDots, $children, keys = [], duration, durations = [], durAtt, xml_id, chord, chord_opts, atts;
+        var me = this, i, j, hasDots, children, keys = [], duration, durations = [], durAtt, xml_id, chord, chord_opts, atts;
 
-        $children = $(element).children();
+        children = $(element).children();
 
         atts = m2v.Util.attsToObj(element);
         durAtt = atts.dur;
@@ -1061,16 +1061,16 @@ var MEI2VF = ( function(m2v, MeiLib, VF, $, undefined) {
           if (durAtt) {
             duration = me.translateDuration(+durAtt);
           } else {
-            for ( i = 0, j = $children.length; i < j; i += 1) {
-              durations.push(+$children[i].getAttribute('dur'));
+            for ( i = 0, j = children.length; i < j; i += 1) {
+              durations.push(+children[i].getAttribute('dur'));
             }
             duration = me.translateDuration(Math.max.apply(Math, durations));
           }
 
-          for ( i = 0, j = $children.length; i < j; i += 1) {
-            keys.push(me.processAttsPitch($children[i]));
-            // dots.push(+$children[i].getAttribute('dots'));
-            if ($children[i].getAttribute('dots') === '1')
+          for ( i = 0, j = children.length; i < j; i += 1) {
+            keys.push(me.processAttsPitch(children[i]));
+            // dots.push(+children[i].getAttribute('dots'));
+            if (children[i].getAttribute('dots') === '1')
               hasDots = true;
           }
 
@@ -1089,7 +1089,7 @@ var MEI2VF = ( function(m2v, MeiLib, VF, $, undefined) {
 
           var allNoteIndices = [];
 
-          $children.each(function(i) {
+          children.each(function(i) {
             me.processNoteInChord(i, this, element, chord);
             allNoteIndices.push(i);
           });

src/Interface.js

@@ -2,66 +2,108 @@
  * @class MEI2VF
  * @singleton
  */
-var MEI2VF = ( function(m2v, MeiLib, VF, $, undefined) {
+var MEI2VF = (function(m2v, MeiLib, VF, $, undefined) {
     return {
+      /**
+       * enables or disables MEI2VF logging
+       * @method setLogging
+       * @param {Boolean} value True if logging should be enabled, false if not. Defaults to false.
+       */
       setLogging : m2v.setLogging,
+      /**
+       * The methods in Converter can be used to manually address distinct
+       * processing steps and retrieve the created data. Can be used in
+       * addition or as a supplement to {@link render_notation} and
+       * {@link rendered_measures}
+       */
       Converter : {
-        initConfig : function(c) {
-          return m2v.Converter.prototype.initConfig(c);
+        /**
+         * initializes the converter
+         * @method initConfig
+         * @param {Object} config The options passed to the converter. For a list, see
+         * {@link MEI2VF.Converter#defaults}
+         */
+        initConfig : function(config) {
+          m2v.Converter.prototype.initConfig(config);
         },
-        process : function(c) {
-          return m2v.Converter.prototype.process(c);
+        /**
+         * Processes the specified MEI document or document fragment. The generated
+         * objects can be processed further or drawn immediately to a canvas via
+         * {@link #draw}.
+         * @method process
+         * @param {XMLDocument} xmlDoc the XML document
+         */
+        process : function(xmlDoc) {
+          m2v.Converter.prototype.process(xmlDoc);
         },
-        draw : function(c) {
-          return m2v.Converter.prototype.draw(c);
+        /**
+         * Draws the processed data to a canvas
+         * @method draw
+         * @param ctx The canvas context
+         */
+        draw : function(ctx) {
+          m2v.Converter.prototype.draw(ctx);
         },
+        /**
+         * returns a 2d array of all Vex.Flow.Stave objects, arranged by
+         * [measure_n][staff_n]
+         * @method getAllVexMeasureStaffs
+         * @return {Vex.Flow.Stave[][]} see {@link MEI2VF.Converter#allVexMeasureStaffs}
+         */
         getAllVexMeasureStaffs : function() {
           return m2v.Converter.prototype.getAllVexMeasureStaffs();
         },
+        /**
+         * Returns the width and the height of the area that contains all drawn
+         * staves as per the last processing.
+         *
+         * @method getStaffArea
+         * @return {Object} the width and height of the area that contains all staves.
+         * Properties: width, height
+         */
         getStaffArea : function() {
           return m2v.Converter.prototype.getStaffArea();
         }
-      }
-    };
-  }(MEI2VF || {}, MeiLib, Vex.Flow, jQuery));
+      },
+      /**
+       * Contains all Vex.Flow.Stave objects created when calling {@link #render_notation}.
+       * Addressing scheme: [measure_n][staff_n]
+       * @property {Vex.Flow.Stave[][]} rendered_measures
+       */
+      rendered_measures: null,
+      /**
+       * Main rendering function.
+       * @param {XMLDocument} xmlDoc The MEI XML Document
+       * @param {Element} target An svg or canvas element
+       * @param {Number} width The width of the print space in pixels. Defaults to 800 (optional)
+       * @param {Number} height The height of the print space in pixels. Defaults to 350 (optional)
+       * @param {Number} backend Set to Vex.Flow.Renderer.Backends.RAPHAEL to
+       * render to a Raphael context; if falsy, Vex.Flow.Renderer.Backends.CANVAS
+       * is set (optional)
+       * @param {Object} options The options passed to the converter. For a list, see
+       * {@link MEI2VF.Converter#defaults} (optional)
+       */
+      render_notation: function (xmlDoc, target, width, height, backend, options) {
+        var ctx;
+        var cfg = options || {};
 
-/**
- * @property
- */
-MEI2VF.rendered_measures = null;
+        ctx = new VF.Renderer(target, backend || VF.Renderer.Backends.CANVAS).getContext();
 
-/**
- * Basic rendering function. Uses the m2v.Converter's prototype as a
- * singleton. No scaling; page layout information in the MEI code is ignored.
- * @param {XMLDocument} xmlDoc The MEI XML Document
- * @param {XMLElement} target An svg or canvas element
- * @param {Number} width The width of the print space in pixels
- * @param {Number} height The height of the print space in pixels
- * @param {Number} backend Set to Vex.Flow.Renderer.Backends.RAPHAEL to
- * render to a Raphael context; if falsy, Vex.Flow.Renderer.Backends.CANVAS
- * is set
- * @param {Object} options The options passed to the converter. For a list, see
- * {@link MEI2VF.Converter MEI2VF.Converter}
- */
-MEI2VF.render_notation = function(xmlDoc, target, width, height, backend, options) {
-  var ctx;
-  var cfg = options || {};
+        width = width || 800;
+        height = height || 350;
 
-  ctx = new Vex.Flow.Renderer(target, backend || Vex.Flow.Renderer.Backends.CANVAS).getContext();
-
-  width = width || 800;
-  height = height || 350;
-
-  if (+backend === Vex.Flow.Renderer.Backends.RAPHAEL) {
-    ctx.paper.setSize(width, height);
-  }
+        if (+backend === VF.Renderer.Backends.RAPHAEL) {
+          ctx.paper.setSize(width, height);
+        }
 
-  cfg.page_width = width;
+        cfg.page_width = width;
 
-  this.Converter.initConfig(cfg);
-  this.Converter.process(xmlDoc[0] || xmlDoc);
-  this.Converter.draw(ctx);
-  this.rendered_measures = this.Converter.getAllVexMeasureStaffs();
+        this.Converter.initConfig(cfg);
+        this.Converter.process(xmlDoc[0] || xmlDoc);
+        this.Converter.draw(ctx);
+        this.rendered_measures = this.Converter.getAllVexMeasureStaffs();
 
-};
+      }
+    };
 
+  }(MEI2VF || {}, MeiLib, Vex.Flow, jQuery));