Release Notes for "jaabc2ps" version 1.1.0, October 27, 2000
John Atchley,

jaabc2ps is a command-line utility that produces near publication quality sheet music from abc music notation files.  An application like Ghostview is required to view and print the output files, unless you have a postscript printer.  Ghostview is free and available for Windows 9x/NT/2000 as well as Linux (it comes bundled with most versions of Linux).

Abc music notation is a simple text format that can be created and read using a text editor like VI or Notepad.  If you are not familiar with abc music notation you should use a web search engine to find the "Abc Home Page," operated by the father of abc notation, Chris Walshaw.

This software is a heavily modified version of "abcm2ps" which in turn is a heavily modified version of abc2ps. See the text file ReadMe.abc2ps for more information.

Both the current version of abcm2ps and this program have changed radically from version 0.9.5 of abcm2ps, the one I started working from.  As a consequence, it's not necessarily easy to roll even a minor feature of one program into the other.

This software is distributed under the GNU Public License (GPL), as was the original.  See the file "License" for more information.

The usual disclaimers apply in regards to liability and so on. Hey, it's free software! If Bill Gates can charge big bucks for buggy commercial software and not be liable for losses..., well, I'm sure you get the idea.

Q U I C K   S T A R T

N E W   I N   V E R S I O N   1 . 1 . 0

27 October, 2000

  1. Fixed a bug that caused the -B switch (or %%barsperstaff) to not work correctly for multiple voices.  This bug was swatted in abcm2ps but in a later version than I started from.
  2. Added command line switch "-L" – using -L on the command line will cause jaabc2ps to: This feature is handy for those times when you get a zipped file of abcfiles from another platform.  It's also handy for dual-booters who don't have Linux configured to recognize the mime type and copy files across from the DOS partitions properly (yeah, that includes me right now – it's amazing how rusty your Unix/Linux skills can become in five years ;-)
  3. Found all of the original abc and format files that originally shipped with abcm2ps and added them to the distribution.  Updated the make file.
  4. Built and briefly tested this version on a real Linux box.  Changed the source distribution to a Linux tar/gzip file.  Provided RPM file for Linux distribution.
  5. Replaced the single call to gets() with a custom function "safe_gets()."  Note that there was nothing wrong with the original call the way Michael used it but the darned GCC linker kept shouting a dire-sounding warning every time the program was built.  Since I didn't want to receive a plethora of "but GCC says" e-mails, I modified perfectly good code to shut the linker up.  Ironically, this was in the interactive function and I don't think the interactive mode is working anyway!
  6. Deleted the function write_version() as it is no longer used.  This function was called when the -V switch was specified.  I needed the -V switch for voice muting, so that switch no longer prints the version.  The version is displayed every time the program is run anyway.  If you need to get the version number within a shell script, it will be on the first line output by the program.
  7. Changed the default settings for several parameters so that the default behaviour (when no parameter file is used) will be more consistent with the default behaviour of the original abcm2ps version 0.9.5.  I realized that several of the new features I had defaulting to "on" might confuse someone who wasn't expecting them.  So, if you want to take advantage of things like the voice combining, watermarks, or different ways of treating accidentals, you need to specify a format file on the command line using -F or embed suitable %%commands in the abc file.  Note, however, that one major difference in the defaults that I have not removed is that jaabc2ps defaults to US letter size paper instead of A4!
  8. Many thanks to Guido Gonzato for providing some much-needed "second set of eyes" testing of features I would probably never have used and, therefore, would never have known were broken!

N E W   I N   V E R S I O N   1 . 0 . 9

  1. I improved the horizontal spacing, eliminating most of the spacing problems that sometimes occured when voices were combined.
  2. I eliminated the problem that sometimes occured when %%jsastem= was used and voices with different note lengths were combined.
  3. I implemented M:none with four different display options controlled by a *.fmt file parameter or by %%FreeMetStyle=n where: I haven't tested this thoroughly.  In particular I'm a bit worried about spacing on a very horizontally crowded staff.  Also, the abc2ps family of programs uses the meter to establish initial symbol spacing.  I default these parameters to 4/4 for M:none and I haven't tested M:none with more dense (i.e. equivalent to 9/8 or what have you) tunes to make sure it doesn't break.  If somebody breaks it please let me know.  Also, please let me know if there is a something else you'd like to see in addition to the above display options.
  4. I cleaned up the source so it should compile cleanly on other platforms.  In particular, I check for a preprocessor definition of "_MSVC".  If defined, I assume that Visual C++ is being used.  If not, I assume unix or another platform and provide a replacement function for "stricmp."  I also casted some char variables to int in function parameters to shut GCC up.  I tested this using Cygwin and GCC for Cygwin and all seems fine.  I haven't tested it with Linux but it should be okay as the Cygwin GCC is supposed to be a direct port of GCC.  Thanks to Guido for swatting some of these things and letting me know that it wasn't compiling cleanly under GCC.

N E W   F E A T U R E S

This is the first time I've released the software since I began modifying it from abcm2ps about a year and a half ago.  Okay, so I haven't been working on it continuously all that time.  However, I've been using it and adding features as I found I needed them that whole time so there are quite a few new features.  Here's a quick overview of the features or changes I can remember:

  1. The first thing about abcm2ps that irritated me enough to start digging into the source code was the barlines that crossed the vocal space in multi-stave music.  This was the first thing I fixed.
  2. The second thing I fixed, or at least improved, was the rather hokey output that results from multiple voices on a single stave.  It's often necessary to use multiple voices on a stave (as opposed to chords) to handle the situation where there are notes of different durations.  Unfortunately, the output doesn't look very typical or "professional."  In jaabc2ps you can use the CombineVoices (%%CombineVoices yes) to join all voices on each stave to a single stem wherever possible and you can force stem directions for voices using a %%jsastem=dn|def|up switch.  This results in output that looks much more like typical modern printed four-part piano/vocal notation.  There are occasional problems when one voice is beamed and the other is not at a given location.  When that happens just don't use the %%jsastem switch or use %%jsastem=def.  This switch is used for each voice.  The last value encountered for each voice will be used for that voice throughout the entire tune.  The %%jsastem= switch does not have an equivalent in the *.fmt file.
  3. I added a lot of parameters to the format file and made the new ones (and a few of the old ones) self-documenting.  This command...
    jaabc2ps -H > default.fmt
    ...produces a file that shows all of the parameters.  Most parameters that can be set in the *.fmt file can also be set within the abc source file by using the %% syntax.  In other words, to override the *.fmt controlled setting and move roll marks close to the noteheads for a single tune within a file, place %%RollsClose yes in the abc source.  Note that the last such command will always affect the entire tune.  This is not a bug.  It is a result of the way the author of the original abc2ps chose to implement the parser.  All variants of abc2ps (that I know of) scan an entire tune before formatting it for output.
  4. Tinwhistle tablature - select the voice and the key of the whistle, tablature is printed below the staves.  May be combined with any other feature (multiple staves, etc.).  You may output more than one set of tablature (i.e. more than one voice) at a time.
  5. Fretted-instrument tablature - for chromatic, mixolydian (mountain dulcimer), and mixolydian-plus (mountain dulcimer with 6-1/2 fret) and any reasonable number of strings.  As with tinwhistle tablature, this prints below the staves.
  6. You can elect not to output all voices.  If you suppress output of all the voices on a staff, the staff is not printed.
    jaabc2ps -V 2 ...
    will suppress output of voice 2 and so on.
  7. You can elect to print accidentals in the modern way, that is accidentals persist to the next bar line.  You can separately elect to use helper accidentals.  This lets you use a single abc tune file to correctly play the music using abc2midi and to score the music the way modern sheet music typically appears.  This behaviour is controlled using the "CarryAccs" and "HelperAccs" parameters in the *.fmt file (or %%CarryAccs yes/no and %%HelperAccs yes/no within the abc source).
  8. I implemented the draft 1.7.3 standard syntax for decorations (and decoration "shorthand" assignments) and implemented almost all of the mentioned decorations. I've added all the most common musical symbols including codas, segnos, D.S. & D.C., dynamics, accents, breath marks, and crescendos and diminuendos. (Crescendos and diminuendos cannot span a line break.).  The decorations are implemented using !keyword! syntax as described in the 1.7.3 standard.  The U: field is implemented with both a "global" and a "tune" table.  A shortcut definition encountered outside of a tune establishes the shortcut for all subsequent tunes in the file while a shortcut definition encountered in a tune header applies only to that tune.  A definition inside a tune header overrides the global definition (if any) for the duration of that tune.
  9. Implemented the "^text" field, with a few extensions to control final positioning, described later.
  10. The syntax for accompaniment chords, including alternate chords and alternate bass notes, is described in the 1.7.3 standard.  I implemented that syntax exactly as described.  So, the abc syntax "Chd/B(Alt/B)" would produce the output shown below.  This output format was chosen because it is commonly used in many music books that provide guitar chords.

       Chd (Alt)
       --- -----
        B    B
  11. You can now specify the starting page number on the command line.
    jaabc2ps -A -o -N -# 5
    will output page numbers and the first will be page number five.
  12. The PageNumTop parameter in the format file (or the %%PageNumTop yes/no command) can be used to move page numbers to the top of the page.
  13. The PageMirror (%%PageMirror yes/no) and MirrorIndent (%%MirrorIndent val) parameters allow you to produce left/right pages with different margins.  Odd numbered pages are always on the "right" and even numbered pages are always on the "left."  You can use the -# command line parameter to force a page to the desired side.
  14. On a voice-by-voice basis, you can suppress printing of decorations or make them print below the staff instead of above it.  This is done using the numbered NoDecos (%%NoDecos vn yes/no) and DecosBelowSt (%%DecosBelowSt vn yes/no) parameters respectively.
  15. I made a lot of improvements to symbol spacing.  Staffs will rarely "collide" with each other or run into the lyrics now as was previously fairly common.  I now preview each symbol to see how much vertical space it needs before the staff spacing is established.  The preview establishes how much space is really used by notation, decorations (including "^text") and guitar chords.  You can now drop the "staffsep" and other spacing parameters to zero or near zero without causing a lot of collisions.  If you are processing a very large file on a slow machine you will doubtless notice that jaabc2ps runs much more slowly than abcm2ps – this is because a great deal of preprocessing is now being done.  On a fast machine, or with small files, the speed difference is not noticeable.
  16. You can elect three pagination modes using the format file and command line.  The first two always existed, I added the third. In all modes the %%newpage command can be used to manually eject the page.
  17. Note, this function does not presently work with ghostscript/ghostview on Linux systems.  "Watermarked" ps files will crash current Linux versions of ghostscript, apparently ghostsript has not been updated to handle the ps3 extensions.  This feature does work on Windoze using the latest ghostscript/GSView.  Added the capability to "watermark" the output with a light gray copyright notice (or other text) at a 45 degree angle "behind" the music.  The watermark can be up to four short lines.  The text that will be output is set using the "Copyright" (%%Copyright string) parameter in the *.fmt file.  Slashes (/) in that string are interpreted as line breaks.  %%Copyright Copyright (c) 2000,/John S. Atchley will produce two lines of watermark in the output.  The watermark is turned on and off using the Watermark (%%Watermark yes/no) parameter.  The gray level can be adjusted using the WatermarkGray (%%WatermarkGray val) parameter.  The WatermarkDate (%%WatermarkDate yes/no) and WatermarkFile (%%WatermarkFile yes/no) parameters will append the current date and the filename, respectively, to the watermark.  Each takes one of the four available lines.
  18. I made some changes to the way info fields are output.  These weren't corrections so much as tailoring the output to something that more closely fit my needs.

B U G S   S W A T T E D

Keep in mind that jaabc2ps evolved from abcm2ps v. 0.9.5 -- which I have since discovered was not even the latest version even way back when I first began modifying the code. Some of these bugs may separately have been swatted in later versions of abcm2ps. I've swatted a handful of bugs that unfortunately I didn't think to keep a record of.

The files "" and "snbook.fmt" illustrate many of the new features.  "" is a partially complete transcription of a music booklet published about 1917 and the goal of the project is to reproduce as closely as possible the original publication.

T H E   F U T U R E

I don't have big plans for jaabc2ps. In fact, I never intended to put a lot of effort into it to begin with.  I just kept finding shortcomings in abcm2ps and fixing them until the program kind of took on a life of its own (I changed the name to jaabc2ps to avoid confusion).  If you run into bugs let me know and I'll try to swat them. Better yet, if you swat them yourself using the available source, let me know and I'll incorporate the fixes.

I will probably implement John Chambers suggested extension to the K: syntax, whether or not it makes it into the abc standard.  It's not going to be an easy change, because the original abc2ps implemented the key signature as a simple signed integer indicating the number of sharps or flats.  I'll have to look at the changes John made to his version of abc2ps and see how easily those changes can be rolled into jaabc2ps.  I'm not sure when I'll get this change done, but probably sometime in the next couple of decades...

I'm not certain if I'll even attempt to keep up with other changes to the standard because, frankly, jaabc2ps as it presently stands already meets my needs quite well.  All of the changes I made were things I needed "fixed" to suit my needs, I really am not interested in (and haven't time for) developing an all-purpose tool that will make everyone happy.  I'll probably only incorporate standard changes if either I begin using the new syntax myself or if the new syntax begins appearing in a lot of "third party" abc that I want to use.

T I N W H I S T L E   T A B L A T U R E

No custom abc syntax or "%%commands" are needed or implemented for tinwhistle tablature.  The tablature generator is completely implemented in software and interprets standard abc.

Tinwhistle tablature is printed in addition to, not instead of, standard notation. The tinwhistle tablature will appear under the last staff, no matter how many staves appear in the standard notation portion. Each line of whistle tablature displays only the highest note of one voice, but, up to four lines of whistle tablature can be printed. Specifying whistle tablature is easy. On the command line use the "-W" switch. The full syntax is "-WnK" where "n" is the voice number and "K" is the key of the whistle. The key is specified as a pitch letter plus "b" or "_" for flat and "#" or "^" for sharp. As in abc source, commas lower the pitch an octave and apostrophes raise it. (D Bb C# ^C and c' are all valid examples.) -W1D will print whistle tablature for the first voice, and the lowest note on the whistle is the same as the note "D" in the abc source.

Note that there is no space between the -W and the "1D" – this is a change from the other switches and I keep telling myself I should get around to making it consistent. But I've always got actual functionality to add instead...

This is probably a good time to mention the new "-V" switch. That switch "turns off" the specified voice, so that it is not printed. This is especially convenient if you have abc that is in four-part harmony on two staves and you just want to print one part with tablature.

jaabc2ps -e 1 -W1D -V 2 -V 3 -V 4

The above line would print only the first voice, with tinwhistle tablature below the staff.

Up to four lines of whistle tablature can be specified:

jaabc2ps -e 1 -W1D -W2D -W3D, -W4D,

The above line would print four lines of tablature below the staves. The first two would be for a "high whistle" and the second two for a "low whistle." Note that the specification of tablature runs from top to bottom so we would probably want to reverse the order of all of the "-W" switches in the above example (to produce the tab sets in the same order that they presumably appear in the standard notation).

There are no whistle-tablature-specific parameters in the format file.

S T R I N G   T A B L A T U R E

The string tablature generator will do its best to interpret standard ABC.  There are a few "extensions" to the abc syntax that you may use to help the tab generator out.  These extensions are NOT part of the abc standard and should not be used in abc files that you distribute or make publicly available.

Like tinwhistle tablature, string tablature prints in addition to the standard notation and appears below the bottom stave. You can have up to four sets of string tablature, and can mix string tablature and tinwhistle tablature freely. String tablature is printed above whistle tablature. Theoretically, you could have several staves of standard notation, four lines of whistle tablature, and four sets of string tablature from a single run. In practice the output from something like that would be very confusing.

String tablature prints as many notes as possible from a single voice. If you have used the new voice joining option, the tablature will use all notes that were joined to a single stem for the specified voice.

String tablature is specified on the command line similarly to whistle tablature. Square brackets below denote optional items, don't actually use the brackets on the command line.

"n" is the voice number just as for whistle tablature. "F" is the fret spacing and must be one of: C - chromatic (guitar, for example) D - mountain dulcimer (mixolydian) D+ - mountain dulcimer with a 6-1/2 fret "P" - each "P" is the pitch of one string or course of strings. The pitch is specified exactly as in abc source. One to eight strings may be specified. "c" is an optional capo fret. When this parameter is present no frets lower than the specified number will be used. ":marked" is an optional parameter specifying that the open string (or capo fret) is to be explicitly marked whenever an up or down bow is encountered in the music. For notes that do not have an up or down bow only the notes actually present in the abc are tabbed. This is useful for a "bum-ditty" style where all strings are swept on the 2 and 4 but only the melody strings are plucked on the 1 and 3, for example. ":simple" is the default -- only notes that actually exist in the abc source are tabbed.

The following extended syntax may be used in the abc source to "assist" the tablature generator and to add some commonly used string tablature symbols.  These extensions are NOT part of the abc standard and should not be used in abc files that you distribute or make publicly available!  They should also be used sparingly.  Abc is not a very good language for describing tablature.  If you find yourself using these extensions a great deal then you would probably be far better off to get a program such as Tabledit that is principly designed for producing tablature.

All string tablature extensions begin with an "at" sign (@).  These extensions immediately precede the abc note that they apply to.  No intervening whitespace is permitted.

Once again, these extensions are NOT part of the abc standard, they WILL "break" most abc software, and they should not be used in abc files that you distribute or make publicly available!

T E X T   P O S I T I O N I N G

The "^text" syntax is described in the 1.7.3 draft standard for abc.  I implemented the features described there plus some additional positioning syntax.  The additional positioning syntax should not "break" software that doesn't implement the additional syntax.  At the worst, software that implements only the 1.7.3 draft will print a couple of extra characters with the text in some cases.

Several months ago I made the following illustrated description of my implementation of the "^text" syntax available on my website and asked the folks on the abcuser's mailing list to comment.  I didn't receive any negative comments, so, while I wouldn't be so presumptious as to claim it will appear in a future standard, I consider it "set in stone" as far as jaabc2ps is concerned and have been using it in my own abc files.

There's been some discussion on the abcusers mailing list recently about the need, or lack of need, for text formatting in the "^text" construct of abc. Okay, let's describe it more accurately – I've been making a dang nuisance of myself, pleading for the inclusion of such syntax!

They say a picture is worth a thousand words, and I have five of them (pictures, that is) that hopefully illustrate my point better than words ever can.

This first picture is from a book I'm transcribing. I'm not much of a musician but even I know that "Ritard molto" starts at the beginning of the measure and that "repeat pp" comes at the end of the ending, meaning repeat after the last note has played. The problem is getting an abc syntax that can easily be used by scoring software to print something close to what we see in this printed book and by "smart" player programs to play this properly.

Figure One

The second picture shows how the present abc syntax would currently handle this. It's pretty adequate for the scoring program .

Figure Two

Notice, though, that the abc (see fragment below) for this is going to be very difficult for a smart player program to parse. It's trivial to make a player program recognize common keywords like "retard molto" and "repeat" and dynamics – but far from trivial to make that program guess where the keywords should really be applied if somewhere other than to the note that the text is anchored to. In the present abc syntax the only way to get decent looking output like that in figure two is either to use one long string as shown in the fragment below or to break the text up but assign it to the wrong notes to get the visual spacing correct. Note that in this example both of the instructions ("ritard molto", and "repeat pp") are anchored to the first note in the second repeat.

|1 c/ c/ c d/ f/ f :|2 "^Ritard molto. Repeat pp."c3/4 c/4 d/ c/ B2 |]
w:roll a-long, roll a-long, O'er the dark blue sea.
|1 F/ F/ F F/ F/ F :|2 "^Ritard molto. Repeat pp."E3/4 E/4 F/ E/ D2 |]
|1 a/ a/ a b/ d'/ d' :|2 "^Ritard molto. Repeat pp."a3/4 a/4 a/ f/ f2 |]
|1 f/ f/ f B/ B/ B :|2 "^Ritard molto. Repeat pp."f3/4 f/4 f/ f/ B2 |]
Notice that one requirement to make a single tune file work with both a scoring program and a smart player doesn't require any special syntax. By having parameters in the scoring program to turn off decorations on a voice-by-voice basis we can then put the instructions in all voices, to help human players who are playing just one of many voices and to make player programs work correctly without "guessing" about whether an instruction needs to be applied to more than one voice.

The third figure and following abc source fragment illustrates how we can solve the problem for player programs using the current syntax. But notice that now the formatting has fallen apart in the scoring program.

Figure Three

Yes, this problem could be solved programmatically (especially for a rather simple case like this) in the scoring software. However, for more complex situations on a crowded score the intelligence that must be built into the scoring software quickly exceeds even that required by playing software in the first example above! Furthermore, no matter how good the scoring software is, there are always going to be cases where it chooses a solution that does not satisfy the user for one reason or another.

|1 c/ c/ c d/ f/ f :|2 "^Ritard molto."c3/4 c/4 d/ c/ "^Repeat pp."B2 |]
w:roll a-long, roll a-long, O'er the dark blue sea.
|1 F/ F/ F F/ F/ F :|2 "^Ritard molto."E3/4 E/4 F/ E/ "^Repeat pp."D2 |]
|1 a/ a/ a b/ d'/ d' :|2 "^Ritard molto."a3/4 a/4 a/ f/ "^Repeat pp."f2 |]
|1 f/ f/ f B/ B/ B :|2 "^Ritard molto."f3/4 f/4 f/ f/ "^Repeat pp."B2 |]

The fourth figure illustrates the first element, justification, of the new syntax that I'm using in text fields. Note that it's still not perfect, as we now have text colliding. (Actually, I could have used center justification here and it would have been almost perfect, but that wouldn't have let me illustrate the last element of the text formatting...)

Figure Four

|1 c/ c/ c d/ f/ f :|2 "^Ritard molto."c3/4 c/4 d/ c/ "^{Repeat pp."B2 |]
w:roll a-long, roll a-long, O'er the dark blue sea.
|1 F/ F/ F F/ F/ F :|2 "^Ritard molto."E3/4 E/4 F/ E/ "^{Repeat pp."D2 |]
|1 a/ a/ a b/ d'/ d' :|2 "^Ritard molto."a3/4 a/4 a/ f/ "^{Repeat pp."f2 |]
|1 f/ f/ f B/ B/ B :|2 "^Ritard molto."f3/4 f/4 f/ f/ "^{Repeat pp."B2 |]
Following the initial "^," "<," ">," "_," or "@" that controls positioning and differentiates this from a guitar chord additional formatting characters can be used to further refine the positioning of the text. These characters can appear in any order but any whitespace or non-formatting character turns off the parsing of positioning. Thus, if you need to print a left caret you would use "^ <" -- the space turns off the search for formatting characters. Likewise, "^under_score" would print "under_score" on the score.

The fifth and final figure illustrates use of formatting characters to fine-tune the position of the text.

Figure Four

|1 c/ c/ c d/ f/ f :|2 "^Ritard molto."c3/4 c/4 d/ c/ "^{>>Repeat pp."B2 |]
w:roll a-long, roll a-long, O'er the dark blue sea.
|1 F/ F/ F F/ F/ F :|2 "^Ritard molto."E3/4 E/4 F/ E/ "^{>>Repeat pp."D2 |]
|1 a/ a/ a b/ d'/ d' :|2 "^Ritard molto."a3/4 a/4 a/ f/ "^{>>Repeat pp."f2 |]
|1 f/ f/ f B/ B/ B :|2 "^Ritard molto."f3/4 f/4 f/ f/ "^{>>Repeat pp."B2 |]

The exact amount of movement caused by the formatting characters is up to the software application. In jaabc2ps I've parametized this. If other developers want to be consistent with jaabc2ps you can follow these guidelines: By default text printed below or above the staff ("^", "_", and "@") moves 1/2 of the text decoration font size horizontally and 1/3 of the text decoration font size vertically. These can be customized in the format file or using %%StaffTextHFac fp and %%StaffTextVFac fp respectively. Fp is a floating point number without units that is a multiplication factor for the text decoration font size. In jaabc2ps I use separate, finer, shift factors for the text near noteheads ("<" and ">" text). Here, the default is 1/2 the height of a notehead horizontal and vertical and the parameter to control this is %%NoteTextFac fp. Again, fp is a floating point number without units and is multiplied times the note height to determine the shift distance.