Score2eps

From CCARH Wiki
Revision as of 08:03, 31 December 2011 by Craig (talk | contribs) (→‎Limitations)
Jump to navigation Jump to search

The score2eps program is a PERL script for converting SCORE binary (.MUS, .PAG), ASCII (.pmx, .txt, etc), or ScoreXML files into Encapsulated PostScript (EPS) files using SCORE version 4 for MS-DOS running with dosemu in linux.


Options

Option Name    Description
-d Run in debug mode: the SCORE editor will be displayed while the printing process is running. This is useful to identify problems in the printing process, such as interacting with warning messages in SCORE for large pages.
-l # Limit the maximum lines in a PMX file (does not check binary SCORE files). The default maximum is 1150 lines. If a file contains too many objects which exceeds the display vectors in the SCORE editor, a warning message will appear in the editor which cannot be handled by automated processing (but can be manually dealt with using the -d option). ASCII page files larger than this size will be skipped and a warning message printed so that large page printing can be monitored using the -d option.
-m filename Write the SCORE macro file used to print the pages, but exit before running the macro file. A filename for writing the macrofile is required for this option.
-r Replace any EPS files which already exist. (see also the -s option)
-s Skip any existing EPS files. By default the program will exit with an error if it finds any pre-existing EPS files which it is asked to overwrite. (see also the -r option)
-w dir Set the working directory if not the current working directory.

Description

Input data

Input data files can have three forms: (1) binary SCORE data files which usually end in .mus or .pag, (2) ASCII SCORE macro files describing one page of music, and (3) ScoreXML files which end in .xml or .sxml. Any file which does not end in .mus, .pag, or .*xml* is assumed to be type (2). Data files of these three types can be interleaved in the command-line arguments for score2eps:

   score2eps file1.mus file2.pmx file3.sxml file4.pmx

The result will be at least three EPS files which match the input file(s) basename with an .eps ending:

             file1.eps file2.eps            file4.eps

ScoreXML files can contain multiple pages. Each page output will be stored in a separate .eps file based on the filename base found in the <name> sub-element of the <fileHead> element which proceeds the SCORE data.

Standard input can be used with ScoreXML data files. If standard input is used, then any other data files given as command-line arguments will be ignored.

  cat data.sxml | score2eps

Handling existing EPS files

There are three methods of handing EPS files which already exist before score2eps processes the input files. By default the score2eps program will exit with an error if it is asked to overwrite any pre-existing EPS files. If the -r option is given, then any pre-existing EPS files will be replaced with a new EPS file. Alternatively, the -s option can be used to skip over any EPS file which already exists.

For example, suppose a file 002.eps already exists. Then the following command will generate an error and no data processing will occur:

   score2eps 001.mus 002.mus 003.mus
    
   ERROR: Delete EPS file to continue: ./002.eps

To replace 002.eps with a new version created from the 002.mus file, use the -r option:

   score2eps -r 001.mus 002.mus 003.mus

This command will overwrite the old 002.eps file with a newly generated one using 002.mus.

To skip over EPS files which already exist, use the -s option:

   score2eps -s 001.mus 002.mus 003.mus

This command will not process 002.mus, since 002.eps already exists. The -s option is useful when continuing to print a collection of files which was interrupted for some reason.

Debug mode

The score2eps program will run in debug mode if the -d option is given:

  score2eps -d file.pmx

This option will prevent the graphical display of the SCORE editor from being hidden while the EPS files are being printed. This option is useful for identifying the cause when the score2eps program gets stuck within the dosemu virtual machine and cannot exit properly. In particular this will happen if there are too many objects on a page, and the SCORE editor runs out of display vectors. In that case the SCORE editor will prompt the user with a warning message which must be acknowledged manually (but the page will still be printed in full).

For ASCII SCORE files and data read from ScoreXML files, there is a default limit of 1150 lines of data when printing with score2eps. When ASCII SCORE files or pages within ScoreXML files exceed this limit, then that file/page will be ignored and a warning message will be printed:

  score2eps bigfile.pmx
   
  WARNING: file too big: skipping bigfile.pmx

The files which are skipped over can be printed later, using the -d option to monitor the printing process for display vector error messages in the SCORE editor.

The limit of 1150 lines is arbitrary: the display vector limit depends on the graphical complexity of objects on the page, not the number of objects. If you know that all pages will not cause the display vector error message to occur in the SCORE editor, you can raise the limit with the -l option:

   score2eps -l 5000 *.pmx

Macro file

The -m option can be used to save the macro file which will be used to generate the EPS files. Once score2eps creates the macro file, it will exit without creating the EPS files if the -m option is used. Normally, the program will generate a temporary macro filename which is deleted after the EPS files have been created.

  score2eps -m macro.txt file.pmx

This will create the file macro.txt which can be run within the SCORE editor with the command

   RES macro.txt


Working directory

It is best to start score2eps in the same directory as the data files. The directory currently must be mappable to the C drive (typically ~/.dosemu/drive_c) or the D drive (typically ~/ — your home directory). The -w option can select a directory other than the current working directory. However, this option needs more testing after the revision of the program.

Examples

Short example

Here is a short example expressed in four different format: (1) SCORE command-based macro file, (2) SCORE binary data file, (3) SCORE numeric macro file (PMX) file, and (4) a ScoreXML data file.

  score2eps shortex1.txt shortex2.mus shortex3.pmx shortex4.sxml

This command will create 4 EPS files: shortex1.eps, shortex2.eps, shortex3.eps, and shortex4.eps which can be viewed in GhostView. These files all represent the same graphical music. They can be converted into PDF files with this command:

      cat shortex1.eps | ps2pdf -dCropEPS - - > shortex1.pdf
  # or
      ps2pdf -dCropEPS shortex1.eps

In this case the -dCropEPS option uses the BoundingBox information from the EPS to define the border of the PDF file:

Shorex-in-acrobat.png


Long example

Here is a ScoreXML data file for Beethoven's Eroica symphony consisting of 169 pages: beethoven-sym3.sxml. This file can be converted into 169 EPS files with the command:

     score2eps beethoven-sym3.sxml -l5000
 # or 
     cat beethven-sym3.sxml | score2eps -l5000

The -l (lowercase L) option is need since a few pages exceed the score2eps limit of 1150 objects on a page (but none of these pages will exceed the display vector limit).

Here is a PDF file created from all of the resulting EPS files using Adobe Acrobat Professional: beethoven-sym3.pdf.

Limitations

  • If overly dense pages are printed, you should use the -d option to monitor the progress of the printing in the SCORE editor. You will have to press "any key" if the display vectors maximum is exceeded (but the page will still print completely).
  • Debugging mode (with -d option) requires an X-windows display. The non-debugging mode can be done without X-windows.
  • You should use filenames which contain 8+3 characters (8 characters for the filename base, and 3 for the filename extension).
  • ScoreXML files are presumed to be neatly formatted so that each <obj> element is on a separate line. Also, the name of each file must be on the same line as the <name> element.

Installation

Download

Download this file and save to a location in your command path, such as /usr/local/bin/score2eps. You can see what directories will be searched for commands by typing this command in a terminal:

  echo $PATH

Once the file is saved onto your hard disk, change the permissions so that it can be run. Type in the terminal:

   chmod 0755 score2eps

(or give the absolute path name if your current working directory is different from the save location.)

To verify that the program is installed properly, type:

  which score2eps

and the terminal should reply something like:

   /usr/local/bin/score2eps

To run the program you must first install dosemu and SCORE v4. Running the program with the -m option does not require dosemu or SCORE.

Getopt::Mixed

To run the score2eps program, you will probably need the PERL module Getopt::Mixed. To install, type as root:

   perl -MCPAN -e shell

If you have not used this command before there will be some setup questions. After initialization, type this command in at the PERL prompt:

   install Getopt::Mixed

If you have run the perl -MCPAN command before, then you can also type this from the command-line to install the package in one step (as root):

   perl -MCPAN -e "install Getopt::Mixed"