Update documentation.

README.md

@@ -1,86 +1,42 @@
 Prerequisites
 =============
 
-fftw fftw-devel atlas atlas-devel alsa-lib alsa-lib-devel fltk fltk-devel
+libcm fftw fftw-devel atlas atlas-devel alsa-lib alsa-lib-devel
 
 
+About
+=====
 
-In the 'template generation' mode the program generates a text file that contains information
-of interest from the MusicXML file. We refer to the text file as the as the 'decoration' file
-because it allows the score to be further decorated by adding additional information to the score.
+`cmtools` is a wrapper program for a collection of utility programs implemented by `libcm`.
+It is particullary useful for a variety of score processing tasks. 
 
-In the 'escore generation' mode the program outputs a data file in CSV format which contains
-the score in a format which is conveniently readable by a score matching program. The program
-also generates a MIDI file which allows the clarified score to be rendered with a sampler.
-An additional SVG (scalable vector graphics) file is generated which shows the score in
-piano roll form along with any problems that the program may have had during the conversion process.
+Electronic Score Generation and Merging
+=======================================
 
+Parse a MusicXML file and generate a textual representation which can be augmented manually or programatically.
+The textual representation is referred to as a 'score edit file' or sometimes just 'edit file'.
 
+This command will generate an edit file as long as the specified edit file does not already exist.
 
 ```
-cmtool --score_gen -x <xml_file> -d <dec_fn> {-c <csvOutFn>} {-m <midiOutFn>} {-s <svgOutFn>} {-r report} {-b begMeasNumb} {t begTempoBPM}
-
-
-Enumerated group: Action selector 
-
-    -S --score_gen  
-    Run the score generation tool.
-
-    -T --timeline_gen  
-    Run the time line generation tool.
-
-    -M --meas  
-    Generate perfomance measurements.
-
--x --xml_fn <filename> 
-    Name of the input MusicXML file.
-
--d --dec_fn <filename> 
-    Name of a score decoration file.
-
--c --csv_fn <filename> 
-    Name of a CSV score file.
-
--p --pgm_rsrc_fn <filename> 
-    Name of program resource file.
-
--m --midi_out_fn <filename> 
-    Name of a MIDI file to generate as output.
-
--i --midi_in_fn <filename> 
-    Name of a MIDI file to generate as output.
-
--s --svg_fn <filename> 
-    Name of a HTML/SVG file to generate as output.
-
--t --timeline_fn <filename> 
-    Name of a timeline to generate as output.
-
--r --report_fn <filename> 
-    Name of a status file to generate as output.
+cmtools --score_gen -x <xml_file> -d <edit_fn>
+```
 
--f --debug_fl  (required)
-    Print a report of the score following processing.
+The edit file generated by this command provides a way to link additional information
+to the score.  [The details for editing the file are here.](https://gitea.larke.org/klarke/cmtools/src/branch/master/doc/xscore_gen.md).
 
--b --beg_meas <int> 
-    The first measure the to be written to the output CSV, MIDI and SVG files.
+Once the edit file has been completed the MusicXML and edit file information can
+be merged to create an 'electronic score' in the form of a CSV file using the following command. 
 
--e --beg_bpm <int> 
-    Set to 0 to use the tempo from the score otherwise set to use the tempo at begMeasNumb.
-	
--n --svg_stand_alone_fl 
-    Write the SVG output with an HTML wrapper.
+```
+cmtools --score_gen -x <xml_file> -d <edit_fn> {-c <csvOutFn>} {-m <midiOutFn>} {-s <svgOutFn>} {-r report} {-b begMeasNumb} {t begTempoBPM}
+```
 
--z --svg_pan_zoom_fl
-    Include the SVG pan-zoom control (--svg_stand_alone must also be enabled)
+Along with the CSV file this command can also generate an SVG (scalable vector graphics) file which shows the
+augmented score in piano roll form, and a MIDI file which can be used to render the score with a synthesizer.
 
--h --help  
-    Print this usage information.
 
--v --version  
-    Print version information.
 
-```
 
 
 Score Following and Timeline Marker Generator
@@ -90,7 +46,7 @@ Perform score following based tasks.
 Generate the time line marker information used by the performance program resource file.
 
 ```
-cmtool --score_follow -c <csv_score_fn> -i <midi_in_fn> -r <report_fn> -s <svg_out_fn> -m <midi_out_fn> -t <timeline_fn>
+cmtools --score_follow -c <csv_score_fn> -i <midi_in_fn> -r <report_fn> -s <svg_out_fn> -m <midi_out_fn> -t <timeline_fn>
 ```
 
 If `<midi_out_fn>` is given then the a copy of `<midi_in_fn>` will be created with 
@@ -126,7 +82,7 @@ is used as a substitute for a real player.
 
 
 ```
-cmtool --meas_gen -p <pgm_rsrc_fn> -r <report_fn>
+cmtools --meas_gen -p <pgm_rsrc_fn> -r <report_fn>
 ```
 
 
@@ -147,7 +103,7 @@ Example `<pgm_rsrc_fn>`:
 Example call with output file snippet:
 
 ```
-cmtool --meas_gen -g ~/src/cmtools/examples/perf_meas/pgm_rsrc_round2.js -r ~/src/cmtools/examples/perf_meas/perf_meas_out.js
+cmtools --meas_gen -g ~/src/cmtools/examples/perf_meas/pgm_rsrc_round2.js -r ~/src/cmtools/examples/perf_meas/perf_meas_out.js
 
 {
   meas : 
@@ -187,7 +143,7 @@ Score Report
 Generate a human readable score report from a score CSV file.
 
 ```
-cmtool --score_report -c <csvScoreFn> -r <scoreRptFn>"
+cmtools --score_report -c <csvScoreFn> -r <scoreRptFn>"
 
 ```
 
@@ -225,7 +181,7 @@ Score Merge
 Copy the manual edits from 'frag.txt' to the correct location, beginning with measure 284, in the blank edit file 'edit0.txt'.
 
 ```
-cmootls  --merge_edit -d edit0.txt  -b 284 -k frag.txt -o temp.txt
+cmtools  --merge_edit -d edit0.txt  -b 284 -k frag.txt -o temp.txt
 ```
 
 All the events in 'frag.txt' may not be able to be located in 'edit0.txt'. Warning messages will be generated for
@@ -250,7 +206,7 @@ MIDI File Reports
 
 Generate a MIDI file report and optional SVG piano roll image."
 
-    cmtool --midi_report -i <midiInFn> -r <midiRptFn> {-s <svgOutFn> {--svg_stand_alone_fl} {--svg_pan_zoom_fl}  }
+    cmtools --midi_report -i <midiInFn> -r <midiRptFn> {-s <svgOutFn> {--svg_stand_alone_fl} {--svg_pan_zoom_fl}  }
 
 
 Timeline Report
@@ -258,7 +214,7 @@ Timeline Report
 
 Generate human readable report from a time line setup file.
 
-    cmtool --timeline_report -t <timelineInFn> -l <tlPrefix> -r <rptOutFn>
+    cmtools --timeline_report -t <timelineInFn> -l <tlPrefix> -r <rptOutFn>
 
 tlPrefix is the folder where data files for this timeline are stored.	
 
@@ -266,7 +222,7 @@ tlPrefix is the folder where data files for this timeline are stored.
 Score Follow Report
 ===================
 
-    cmtool  --score_follow -c round2.csv -i new_round2.mid -r report.txt -s report_svg.html
+    cmtools  --score_follow -c round2.csv -i new_round2.mid -r report.txt -s report_svg.html
  
  
 SVG Description
@@ -276,7 +232,8 @@ SVG Description
 - Red borders around MIDI events that did not match.
 - Line is drawn to MIDI events that matched to multiple score events. The lines
 are drawn to all score events after the first match.
- 
+   
+   ![Example SVG Image](doc/score_follow_0.png)
 
 Audio Device Test
 =================
@@ -291,18 +248,18 @@ This test also excercises the real-time audio buffer which implements most of th
 ```
 
 ```
--s --srate <real>     Audio system sample rate.
--z --hz <real>     Tone frequency in Hertz.
--x --ch_index <uint>     Index of first channel index.
--c --ch_cnt <uint>     Count of audio channels.
--b --buf_cnt <uint>     Count of audio buffers. (e.g. 2=double buffering, 3=triple buffering)
--f --frames_per_buf <uint>     Count of audio channels.
+-s --srate <real>            Audio system sample rate.
+-z --hz <real>               Tone frequency in Hertz.
+-x --ch_index <uint>         Index of first channel index.
+-c --ch_cnt <uint>           Count of audio channels.
+-b --buf_cnt <uint>          Count of audio buffers. (e.g. 2=double buffering, 3=triple buffering)
+-f --frames_per_buf <uint>   Count of audio channels.
 -i --in_dev_index <uint>     Input device index as taken from the audio device report.
--o --out_dev_index <uint>     Output device index as taken from the audio device report.
--r --report_flag     Print a report of the score following processing.
--h --help      Print this usage information.
--v --version      Print version information.
--p --parms      Print the arguments.
+-o --out_dev_index <uint>    Output device index as taken from the audio device report.
+-r --report_flag             Print a report of the score following processing.
+-h --help                    Print this usage information.
+-v --version                 Print version information.
+-p --parms                   Print the arguments.
 ```
 
 MIDI Audio Sync (MAS)

doc/xscore_gen.md

@@ -1,7 +1,7 @@
-xscore_gen
+score_gen
 ==========
 
-*xscore_gen* parses MusicXML score files and generates a text file
+The `cmtools` *score_gen* command parses MusicXML score files and generates a text file
 which allows the score to be clarified and additional information to
 be added.  This is the first step in creating a 'machine readable
 score' based on the 'human readable score'.
@@ -25,15 +25,15 @@ text strings.
 
 2. Generate the MusicXML file using the [Dolet 6 Sibelius
 plug-in](https://www.musicxml.com/).  The resulting MusicXML file is
-run through *xscore_gen* and parsed to find any invalid structures
+run through *score_gen* and parsed to find any invalid structures
 such as damper up events not preceeded by damper down events, or tied
 notes with no ending note. These problems are cleared by careful
 re-editing of the score within Sibelius until all the problematic
 structures are fixed.
 
-3. As a side effect of step 2 a template 'decoration' file is generated.
+3. As a side effect of step 2 a template 'edit' file is generated.
 This text file has all the relavant 'machine score' information 
-from the XML score as a time tagged list. In this step *decoration* information is manually
+from the XML score as a time tagged list. In this step *edit* information is manually
 added by entering codes at the end of each line.  The codes
 are cryptic but they are also succinct and allow for relatively
 painless editing.
@@ -50,7 +50,7 @@ cmtools --score_gen -x GUTIM_20200803_utf8.xml -d edit0.txt -c score.csv -m scor
 ```
 
 As with step 2 this step may need to be iterated several times
-to clear syntactic errors in the decoration data.
+to clear syntactic errors in the edit data.
 
 5. Generate the time line marker information to be used with the performance program:
 
@@ -78,15 +78,15 @@ There are currently three defined groups
 
 ### Score Coloring Chart:
 
-Description         Number   Color
-------------------- -------- -------------------------
-Even                #0000FF  blue 
-Tempo               #00FF00  green
-Dyn                 #FF0000  red
-Tempo + Even        #00FFFF  green + blue (turquoise)
-Dyn   + Even        #FF00FF  red   + blue
-Dyn   + Tempo       #FF7F00  red   + green (brown)
-Tempo + Even + Dyn  #996633  purple
+Description         | Number   | Color
+------------------- | -------- | -------------------------
+Even                | #0000FF  | blue 
+Tempo               | #00FF00  | green
+Dyn                 | #FF0000  | red
+Tempo + Even        | #00FFFF  | green + blue (turquoise)
+Dyn   + Even        | #FF00FF  | red   + blue
+Dyn   + Tempo       | #FF7F00  | red   + green (brown)
+Tempo + Even + Dyn  | #996633  | purple
 
 Decrement color by one (i.e. 0xFE) to indicate the last note in a group
 of measured notes.  Note that a decremented color stops all active measures
@@ -134,14 +134,14 @@ this problem by editing the first line with `vi`.
 
 
 
-Create the decoration file
+Create the edit file
 --------------------------
 
 ```
-cmtools --score_gen -x myscore.xml -d mydec.txt {--damper}
+cmtools --score_gen -x myscore.xml -d myedit.txt {--damper}
 ```
 
-Here's a snippet of a typical 'decoration' file.
+Here's a snippet of a typical 'edit' file.
 
 ```
 Part:P1
@@ -165,7 +165,7 @@ Part:P1
        14   5     0    3072   768  4.0     -R------------- 3840
 ```
 
-### Decoration file format
+### Edit file format
 
 Column | Description
 -------|-----------------------------
@@ -179,7 +179,7 @@ flags  | event attributes
 
 ### Event attribute flags:
 
-Event attribute symbols used in the decoration file:
+Event attribute symbols used in the edit file:
 
 Desc      | Flag | 
 ----------|------|-----------------------------------------
@@ -204,7 +204,7 @@ Onset     |  *   | note onset
 
 
 
-Decoration Sytax:
+Edit Sytax:
 ------------------
 
 ```