cmXScore.h/c : Improved comments. cmXScoreTest() now calls cmXScoreGenEditFile() when editFn arg is given and the associated file does not exist.

app/cmXScore.c

@@ -2359,7 +2359,7 @@ cmXsRC_t _cmXsApplyEditFile( cmXScore_t* p, const cmChar_t* fn )
             if((rc = _cmXScoreReorderParseDyn(p,b,ln+1,&r.dynIdx)) != kOkXsRC )
               goto errLabel;
             
-            // parse the flag edits
+            // parse the flag edits following a '~'
             if((rc = _cmXScoreReorderParseFlags(p,b,ln+1, &r.newFlags)) != kOkXsRC )
               goto errLabel;
 
@@ -3694,6 +3694,14 @@ cmXsRC_t cmXScoreTest(
   cmXsRC_t rc;
   cmXsH_t h = cmXsNullHandle;
 
+  if( editFn!=NULL && !cmFsIsFile(editFn) )
+  {
+    cmRptPrintf(&ctx->rpt,"The edit file %s does not exist. A new edit file is therefore being created.",editFn);
+    cmXScoreGenEditFile(ctx,xmlFn,editFn);
+    editFn = NULL;
+  }
+  
+
   // Parse the XML file and apply the changes in editFn.
   if((rc = cmXScoreInitialize( ctx, &h, xmlFn,editFn)) != kOkXsRC )
     return cmErrMsg(&ctx->err,rc,"XScore alloc failed.");

app/cmXScore.h

@@ -37,7 +37,7 @@ extern "C" {
   //       b. Emacs C-x <RET> f utf-8 <RET>
   //       c. Change: <?xml ... encoding = 'UTF-16' to encoding='UTF-8' ...?>
   //
-  // 2) Replace "DoletSibelius Unknown Symbol Index" with "DoletSibelius unknownSymIdx"
+  // 2) Replace "DoletSibelius Unknown Symbol Index " with "DoletSibelius unknownSymIdx="
   //
   // Steps 1) and 2) can be automated by in emacs by:
   //
@@ -45,9 +45,8 @@ extern "C" {
   //
 
   // Initialize an cmXScore object from a Sibelius generated MusicXML file.
-  // Optionally include an 'edit' file to attach additional score information.
-  // Note that the 'edit' file is created by marking up a file created via
-  // cmXScoreReport().
+  // 'editFn' is used to add additional information to the score.
+  // See cmXScoreGenEditFile()
   cmXsRC_t cmXScoreInitialize( cmCtx_t* ctx, cmXsH_t* hp, const cmChar_t* xmlFn, const cmChar_t* editFn );
   cmXsRC_t cmXScoreFinalize( cmXsH_t* hp );
 
@@ -58,9 +57,18 @@ extern "C" {
 
   void     cmXScoreReport( cmXsH_t h, cmRpt_t* rpt, bool sortFl );
 
+  // Generate a template 'edit file'. This file can be edited by hand to included additional
+  // information in the score. See the 'editFn' argument to cmXScoreInitialize() for where
+  // this file is used.
   cmXsRC_t cmXScoreGenEditFile( cmCtx_t* ctx, const cmChar_t* xmlFn, const cmChar_t* outFn );
 
   // Generate the CSV file suitable for use by cmScore.
+  //
+  // If the file referenced by 'reorderFn' exists then it is used to attach additional
+  // score information.  If it does not then a new edit file is created via an
+  // internal call to cmXScoreGenEditFile().  This file can then be edited
+  // to include the additional score file information and passed back by a later
+  // call to this same function.
   cmXsRC_t cmXScoreTest( cmCtx_t* ctx, const cmChar_t* xmlFn, const cmChar_t* reorderFn, const cmChar_t* csvOutFn, const cmChar_t* midiOutFn );
   
 #ifdef __cplusplus